Google Accounts Authentication and Authorization

Authenticating Users in Mobile Apps

Many web applications have companion mobile applications, such as native Android and iOS apps. These native applications typically ask the user for their email address and password to authenticate them. This method of authentication will not work when the web application has a complex login system which uses technologies like OpenID or SAML for federated authentication. In this guide, we'll describe an alternative technique to enable mobile applications to work for all users, regardless of how they are authenticated.

If you're anxious to see how this works, you can check out the Demo and Sample Code section at the bottom of this page.

Embedding a Web Browser

To enable your mobile application to use web-based protocols like OpenID or SAML for authentication, you'll need to have your users login using a web browser on the mobile device. We recommend that your application embed a web browser for authentication, as opposed to launching the main web browser on the device. There are trade offs between these two approaches, but we've found that the embedded view works best overall.

Embedding a web browser is simple on the common platforms:

The embedded web view should typically point to the URL of a web page on your main web application ("login page"). This page is a mobile-optimized version of your login form, where you enable users to login with either an email address and password or a federated OpenID or SAML identity.

Issuing a Token to the App

After the user successfully logs into your web site, the site will need to redirect the user over to a page which generates a token ("token page"). This token is then passed to the mobile application for authentication.

The generated token should be in a similiar format to what the web application sets for session login cookies. If your site does not use cookies for session management or uses a web framework which cannot be modified, you will need to generate your own digitally signed token with information about the user. Preferrably, the token should have a "mobile flag" set on it which indicates:

  1. The token is only valid for API calls, and the value cannot be passed as a cookie for browsing the web site.
  2. The token doesn't have the typical short lifespan (e.g. 30 mins) of a browser session - it only expires when it is manually revoked or the user's password has been changed (see below).

After generating the token, the web site needs to communicate the value back to the mobile application. This can be done using two different techniques:

  • Cookies: The server can return the token back to the embedded browser as a HTTP cookie, i.e. in a Set-Cookie header. The cookie should have the HttpOnly flag set and, preferrably, be sent over SSL with the Secure flag set as well. The name of the cookie should be well-known (such as auth_token) so it can be accessed by the mobile app.
  • Window Title: The server can include the token in the value of the HTML <title>. The window title value can often be accessed by native applications, but the token can also be vulnerable to leaks if the website has cross-site scripting bugs.

Extracting the Token

After the web site has generated the token and included it in the response via either the Cookie or Window Title techniques discussed above, the mobile app should extract the token and immediately close the embedded web view.

The method used for extracting the token varies depending on the platform and the technique used for returning the token in the response. Here are some hints for common platforms when using Cookies to return the token:

  • Android: CookieManager#getCookie(URL) can be used to extract the cookie set by the "token page" URL. Multiple semicolon-separated cookies may be returned, so you'll need to parse through the response to find the correct cookie, using the well-known name (such as auth_token). Detailed sample code is available for using this technique on Android.
  • iOS: The mobile application can read cookies set by the "token page" using NSHTTPCookieStorage. This is commonly referred to as the "cookie jar."
    NSHTTPCookie *cookie;
    
    NSHTTPCookieStorage *cookieJar = [NSHTTPCookieStorage sharedHTTPCookieStorage];
    for (cookie in [cookieJar cookies]) {
       NSLog(@"%@", cookie);
    }
    Detailed sample code is available for using this technique on iOS.

Calling Your Web Application's APIs

Your mobile application now has a token which can be used to authenticate calls to your application's server-side APIs. Your API server should validate tokens in the same way the website validates standard login coookies. Preferrably, the server would also take into account the "mobile flag" mentioned above.

For the security of your users' data, your application's server-side APIs should require SSL for API access and also should only accept the tokens as HTTP headers instead of as URL query parameters.

Enabling Token Revocation

When a user changes their password on the web application, all previously-issued mobile app tokens should be invalidated. The application should also allow users to disable mobile logins through the website's "Account Management" page.

One technique for implementing the revocation of tokens is by keeping track of the time a user last changed their password:

  • store a timestamp in the web application's database for every user account indicating the time the user’s password was last changed
  • disallow any API calls made using tokens issued before the stored time

Demo and Sample Code

Demo Store

We have a Demo Store web application which you can use to see how this technique works. This Demo Store has a companion Android application.

To try out the demo, we suggest creating an account on the website first (click 'Sign In' at the top of the site to get started). Next, download the Android application and login.

This demo application uses a login experience called an Account Chooser. In this case, this experience is enabled using the Google Identity Toolkit. Of course, you can use any login experience you want on your site.

Sample Code

Complete sample code demonstrating this technique is available for Android and iOS.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.