Custom Authentication with Couchbase Mobile

Couchbase Mobile extends Couchbase to the edge, securely managing and syncing data from any cloud to every mobile device. Couchbase Mobile features an embedded database – Couchbase Lite – with SQL and full-text search for JSON, built-in peer-to-peer synchronization, and end-to-end security from cloud to edge.

Couchbase Mobile also features a secure web gateway – Sync Gateway – that enables data access and synchronization over the web and supports multiple authentication methods. One of these methods is custom authentication where an App Server handles the authentication with an external system.

This blog post will guide you through the custom authentication flow with examples of how to implement the App Server code and the mobile app code. An OpenLDAP server is used in this example, but the flow applies to any external authentication provider.

The example App Server is a simple node.js application and the mobile app code samples use the Couchbase Lite Android SDK.

Prerequisites

This blog assumes familiarity with Couchbase Server, Sync Gateway, and Couchbase Lite.

You will need an operational Sync Gateway 2.5 & Couchbase Server EE 6.x installation. If needed, the following links can get you up and running quickly:

  1. Install Couchbase Server
  2. Install Sync Gateway
  3. Configure Sync Gateway

All code from this blog is available in the following Git repository: https://github.com/dugbonsai/sg-custom-auth

Custom Authentication Flow

The following diagram shows an example custom authentication.

  1. The mobile app user attempts to login with their credentials through a REST interface exposed by the App Server.
  2. The App Server authenticates the user against an OpenLDAP Server.
  3. If the user is not authenticated, the user is returned to the login UI.
  4. If the user is authenticated, the App Server gets the user information from Sync Gateway through a REST interface.
  5. If the user does exist in Sync Gateway skip to step 8.
  6. If the user does not exist in Sync Gateway, the App Server creates a new user in Sync Gateway through a REST interface.
  7. If the user was not created in Sync Gateway, the App Server returns an error and the user is returned to the login UI.
  8. If the user was created in Sync Gateway, the App Server creates a new session for the user in Sync Gateway through a REST interface.
  9. If the session was not created in Sync Gateway, the App Server returns an error and the user is returned to the login UI.
  10. If the session was created in Sync Gateway, the App Server returns the session ID.
  11. The mobile app stores the session ID and creates a Couchbase Lite replicator using the session ID.
  12. If replication fails due to an expired session in Sync Gateway, the user is returned to the login UI.

OpenLDAP Configuration

If you already have an LDAP server configured you can skip this section. If you do not have an LDAP server configured, these instructions will walk you through configuring OpenLDAP on Ubuntu 18.04.

  1. Create an LDIF file (ldap_data.ldif) with information to populate the LDAP database (click here for more details on LDIF files). The instructions for configuring OpenLDAP above also contain instructions for creating the LDIF file to populate the LDAP database. In this example, user mobileuser (starting on line 13) will be used when authenticating from the mobile app.

  1. Add the initial data to the OpenLDAP database:

  1. Test the setup by searching for mobileuser in the OpenLDAP directory:

You will see the information for mobileuser:

App Server Implementation

The App Server is implemented as a node.js application. The full App Server code is available in auth.js in the following Git repository: sg-custom-auth. The App Server uses the passport-ldapauth package for LDAP authentication. The following code snippets highlight the call to authenticate against the OpenLDAP server and the Sync Gateway REST API calls.

The App Server must handle calls to POST /login. This endpoint is called from the mobile app with the user credentials stored in the request body in username and password. The App Server uses these credentials to authenticate against the OpenLDAP server.

The value of searchBase must match the domain components defined in your LDAP server. dc=example,dc=com was used above so the same values are used here (line 12).

The following steps will be executed if the user is authenticated.

Get user information from Sync Gateway

Get user information from Sync Gateway by calling GET /{db}/_user/{name}. If the user exists in Sync Gateway, the response code is 200. If the user does not exist in Sync Gateway, the response code is 404.

If the user does not exist in Sync Gateway, create a new user

Create a new user in Sync Gateway by calling POST /{db}/user/. If the user was successfully created in Sync gateway, the response code is 201.

Create a session for the user in Sync Gateway

Create a session for the user in Sync Gateway by calling POST /{db}/_session. In this example the session will expire after 30 minutes. If the session was successfully created in Sync Gateway, the response code is 200. The JSON response contains the following values:

session_id: the ID for the new session. This will be used by the mobile app for authentication with Sync Gateway.

expires: timestamp when the session expires. This is not used in the mobile app.

cookie_name: name of session cookie. This is not used in the mobile app.

Testing Authentication

To test the authentication from the App Server, start it using the following command:

After it starts you will see the following:

You can test the app sever using a simple curl command as follows (or Postman, etc.):

You will see output similar to the following:

If the user does not exist in LDAP, the response will be:

Output from the App Server will look like this:

Mobile App Implementation

All that is left to do is make the appropriate calls from the Mobile App to the App Server and Sync Gateway. The mobile app uses the Volley framework to make the REST call to the App Server. The following code snippets highlight the call to the App Server and the Couchbase Lite code to authenticate using the session_id.

Authenticate mobile user

Authenticate user with App Server by calling POST /login/

Create one-shot replication

Create one-shot replication using saved session_id (line 13) and re-authenticate if Sync Gateway session has expired.

What’s Next

If you’re new to Couchbase, take advantage of our free, online training available at https://learn.couchbase.com to learn more.

More mobile tutorials can be found at the Couchbase Tutorials web page.

Posted by Douglas Bonser, Principal Solution Engineer, Couchbase

Douglas Bonser is a Senior Solutions Engineer at Couchbase and has been working in IT and technology since 1991. He is based in the Dallas/Ft. Worth area.

Leave a reply