To kick off the Couchbase Mobile Sync Gateway series, we will begin with understanding on how to authenticate and authorize users in Sync Gateway which is the intermediary component between mobile apps and Couchbase Server.
Through Sync Gateway, there are various ways you may authenticate your user base for your mobile application in order to then authorize them to access the remote database. From there onwards, mobile apps can communicate data by replication where data can have bi-directional and multi-master sync. Let us explore the different Authentication Users mechanisms first.
Authentication
HTTP Basic Authentication
The mobile client is able to authenticate through Sync Gateway by using either a session URL where it is determined to be /dbname/_session or using a cookie-based session.
|
1 2 3 |
curl -H "Content-type: application/json" -X POST http://localhost:4984/dbname/_session --data "{"name":"userID","password":"pw"}" |
With the user credentials provided in the session URL POST request, the validation will return the following upon a correct user and password set
|
1 2 3 4 5 |
{ "authentication_handlers":["default","cookie"], "ok":true, "userCtx":{"channels":{"!":1,"channel1":1,"channel2":1},"name":"userID"} } |
Pluggable Authentication
For Couchbase Mobile, the Facebook Authentication method is a pluggable authentication option where Sync Gateway will be communicating to Facebook to authenticate the token for the clients. For us to enable this feature, the top-level property 'facebook' is set to true in the server configuration file for the 'register' key like below.
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "facebook" : { "register" : true }, "databases": { "grocery-sync": { “server”:”http://cbserver:8091”, “bucket":"grocery-sync", "users": {"GUEST": {"disabled": true}}, "sync":`function(doc) {channel(doc.channels);}` } } } |
From there, the mobile client can implicitly register new user accounts by authenticating through Facebook with a POST request to '/dbname/_facebook' and return a JSON that contains:
- access_token: Access token returned by Facebook
- email: User email
- remote_url: Sync Gateway Endpoint
The user name for the account is the same as the authenticated email address along with a random password.
Custom Authentication
There are a couple of advantages of having a custom auth for your mobile application in that you do not need to be dependent in 3rd party solutions like the previous pluggable Facebook method. There is overall more work involved where you have to maintain the service that communicates with the Sync Gateway along with the respective end point calls from the mobile app. This will be dependent if you have an existing user base in like an LDAP server or that the client may need to have the feature to create an user name and password combination.
To implement a custom provider where an user base exists in an LDAP server setup is where the mobile application points to the app or auth server first. The auth server is then responsible for authenticating users where once it successfuly authenticates an user, the auth server would make an API call to Sync Gateway Admin REST API in the second step to get a valid session for that user by sending a POST request to '/dbname/_session' endpoint. That session token then gets routed back to the auth server and then returned back to the mobile client. The third and last step once the mobile application obtains the token is then to communicate to Sync Gateway directly using the session token to obtain all the data required for the user on the device.
Once we have authenticated our users, it is time explore the different Authorizing Users mechanisms next.
Authorization
Accounts: admin_channels
Sync Gateway allows for authorizing certain users the right to particular documents within a database. Through the JSON configuration file, which defines Sync Gateway properties, we are able to use the 'admin_channels' feature to enable a list of channels where the user has access to once they are authenticated. Authorizing an user to a particular channel would allow document READ access:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
{ "log" : [“*”], "databases": { "grocery-sync": { “server”:”walrus:”, “bucket":"grocery-sync", "users": { “alice”: { “disabled” : false, “password”: “password”, “admin_channels”:[“items-alice”] }, “bob”: { “disabled” : false, “password”: “password”, “admin_channels”:[“*”] }, “sync” : ‘ function(doc, oldDoc) { channel(“items-”+doc.owner); } //Add item document to owner’s items channel ‘ } } } } |
In the example above, the * Star channel is a special channel that provides administraton privileges for a particular user, Bob, where Bob is granted open ended access to all the documents within a database. Alice on the other hand will have access to her own items channel that is specific to 'items-alice' tag and therefore in the authorization scheme, Alice is then authorized. To enable the authorization to occur, the owner field in a grocery item document needs to be linked to the owner personal items channel accordingly.
The Sync Function will enable the ability for users to submit revisions to documents by checking if the users are authorized to access the document. How that is done is by assigning Account properties like 'password' above in the example or 'roles' to the users where authorized users can then access Sync Gateway and control their remote database. The 'admin_channel' and 'password' are two of the available Account properties that can be used to authorize user access to the remote database through Sync Gateway.
In the follow up Sync Gateway blog series, we will explore how 'Channels' enable particular users to be able to read a document in the database and learn how data is routed.
I think this needs a bit more detail, the POST to the public url only gets a temporary session which is best deleted