Using OAuth APIs provided by 3rd party applications such as Google+ to login in your mobile app can provide a delightful first time experience to users. They can login with an account that they already know and trust and populate their profile with data that they entered on Google+. In this tutorial, you’ll learn how to:

  • Write a Node.js app to handle the authentication with Sync Gateway.
  • Use the Couchbase Sync Gateway Admin REST API to create users and sessions.
  • Integrate Google Sign-In to an iOS app written with Swift 2.
  • Build a simple iOS app in Swift to test the new login endpoint and replicate a few documents.

The final project can be found on GitHub.


The prerequisites for this tutorial are:

  • Node.js
  • Xcode 7+ (you will use Swift 2 to build the sample app)

Getting Started

Download Sync Gateway from the link below and unzip the file:

In a new file named sync-gateway-config.json, paste in the following:

In this config file, you’re creating a database called simple-login and using the Sync Function to map each document to a different channel and grant a user access to the channel (the user name being stored in the user_id field of the document).

Start Sync Gateway with the following command:

Reverse Proxy for Sync Gateway

With Sync Gateway running, you get to shift your focus to building the App Server to handle authentication between Google and Sync Gateway.

You’ll use the popular Express module to handle the request to create a user and the request module to proxy all other traffic to Sync Gateway.

Install the following Node.js modules:

Create a new file called server.js and add the following:

Here are the different things happening:

  1. Require the Node.js module you installed previously.
  2. Instantiate a new instance of express and use the bodyParser middleware only for the /google_signin endpoint.
  3. Proxy all other requests to Sync Gateway.
  4. Start the Node.js web server on port 8000.

Start the server with $ node server.js and open http://localhost:8000 in your browser. You should see the Sync Gateway welcome message:

From Google SignIn to Sync Gateway Sessions

With the reverse proxy in place you can now add some code to handle the Google SignIn request and return the session credentials:

A few things are happening on this diagram:

  • Black sends the Google user ID to the App Server.
  • Blue checks if a user exists in Sync Gateway with that user ID.
  • Orange creates the user if it doesn’t already exist (typically the first time the user logs in with Google in your app).
  • Green creates a session, the response will contain session credentials that can be passed to the client iOS app for push/pull replications. All of the Couchbase Lite SDKs have a method to specify session credentials to be used in push/pull replications.

In the /google_signin handler, add the following:

Restart the Node.js application and run the following curl request to sign up a new user:

In the next section, you will create a simple a iOS app with Swift 2 to use the new functionality of your App Server.

Swift Time: Simple Login Screen for iOS

Switch to Xcode and create a new project with the Single View Application template:

We’ll use Cocoapods to install dependencies in this project. Close the Xcode project and from the command line run $ pod init to migrate your project to using Cocoapods. Open the Podfile and add the statements:

Run $ pod install and open the SimpleLogin.xcworkspace file that was generated. Next, you will add a bridging header to access the Google SignIn and CouchbaseLite SDKs that use Objective-C from your Swift code. In the Xcode project navigator, right-click on SimpleLogin and select New File…. Choose the Header File template and call it bridging-header.h. Add the following import statements:

Now you need to tell Xcode to use this file. In the SimpleLogin target, select the Build Settings tab and scroll down to the Objective-C Bridging Header. Add this filepath:


Google Sign-In Configuration file

Before you can use the Sign-In SDK in your app, you’ll need to create a new project in the Google Developer Console and generate a client ID. Luckily for us, this can be done automatically with the following link:

On the page above, click the Choose and configure services button and you’ll be taken to a new page where you can enable Google Sign-In. From there, click Generate configuration files and download the new plist file.

Import GoogleServer-Info.plist to your Xcode project:

Adding URL schemes to your project

Google Sign-In requires two custom URL Schemes to be added to your project. To add the custom schemes:

  1. Open your project configuration: double-click the project name in the left tree view. Select your app from the TARGETS section, then select the Info tab, and expand the URL Types section.
  2. Click the + button, and add a URL scheme for your reversed client ID. To find this value, open the GoogleService-Info.plist configuration file, and look for the REVERSED_CLIENT_ID key. Copy the value of that key, and paste it into the URL Schemes box on the configuration page. Leave the other fields blank.
  3. Click the + button, and add a second URL scheme. This one is the same as your app’s bundle ID. In this case, it should be com.couchbase.SimpleLogin.

When completed, your config should look something similar to the following (but with your application-specific values):

Integrating Google Sign-In into your iOS app

Now your project is configured correctly you can start using the SDK to add the Login button on the UI and app logic to retrieve the user info. In AppDelegate.swift, declare that this class implements the GIDSignInDelegate and add the following in the application:didFinishLaunchingWithOptions: method:

Next, implement the application:openURL: method of your app delegate. The method should call the handleURL method of the GIDSignIn instance, which will properly handle the URL that your application receives at the end of the authentication process:

In the app delegate, implement the GIDSignInDelegate protocol to handle the sign-in process by defining the following methods:

Adding the Sign-In Button

Next, you will add the Google Sign-In button so that the user can initiate the sign-in process. In the view controller that manages your app’s sign-in screen, make the class implement the GIDSignInUIDelegate protocol.

In the view controller, override the viewDidLoad method to set the UI delegate of the GIDSignIn object, and (optionally) to sign in silently when possible.

Implement the GIDSignInUIDelegate protocol:

Add a GIDSignInButton to your storyboard, XIB file, or instantiate it programmatically. To add the button to your storyboard or XIB file, add a View and set its custom class to GIDSignInButton.

Run the app and you should now see the Google styled button and be able to login:

Creating a Session with Sync Gateway

In AppDelegate.swift, find the signIndidSignInForUserwithError method and add the following below the existing code:

Here’s what is happening above:

  1. The login URL on the App Server running locally.
  2. Create a request instance.
  3. Serialize the properties containing the Google userID as JSON to be sent in the request.
  4. Send POST request.
  5. Response object containing Sync Gateway Session credentials

NOTE: Before running the application, be sure the disable App Transport security since the App Server isn’t using HTTPS. Open Info.plist and add the following:

Build and run. Notice the response from the App Server in the Xcode debugger:

Finally, you will add the Couchbase code to start a pull replication with the session details. In AppDelegate.m, add the method startReplications:

Call this method in the callback of the uploadTask you added in the previous step.

Et voilà! You now have a pull replication running for the user with name google-{userID}. You can test the access is working by adding a document with the following command (replace the Google user ID with that of a user already logged in):

Head over to the Users tab in the Admin UI at http://localhost:4985/_admin/db/simple-login/users and notice that user google-102898171485172449137 now has access to channel 1234:

Where to Go From Here

Congratulations! You learnt how to use Google SignIn with Couchbase Mobile to create a delightful experience and synchronize documents per the user ID of the logged in user.

Feel free to share your feedback, findings or ask any questions in the comments below or in the forums. Talk to you soon!

Posted by James Nocentini, Technical Writer, Mobile, Couchbase

James Nocentini is the Technical Writer in charge of the documentation for Couchbase Mobile. Previously, he worked as a Developer Advocate and before that as a front-end developer for HouseTrip. He also enjoys writing Android tutorials for in his spare time.

Leave a reply