Google+ Platform

Migrating to Google+ Sign-In

Steps to migrate from other authentication services

Google has simplified and enhanced two areas:

Sign-in services - Over the years, Google has supported a number of ways to authenticate users in your apps. To make our APIs simpler, we are consolidating our authentication support to OpenID Connect. Google+ Sign-in is a library built on OpenID Connect and is the fastest and easiest way to integrate sign-in into your sites and apps. In December 2013 we enhanced Google+ Sign-In to work for all users, even if they have not created a Google+ profile.

Getting user profile information - Google has been providing two endpoints for getting user profile information (including email addresses). To simplify our APIs, we are consolidating support to people.get (and the OpenID-compliant version people.getOpenIdConnect), and ending support for the userinfo endpoint.

Changes

Sign-in services - To simplify sign-in, Google is making the following changes:

  • We will no longer support OAuth 2.0 login (early version) on Sept. 1, 2014. (New)
  • We have deprecated and will shut down OpenID 2.0 on April 20, 2015, after a migration period. (New)
  • We have scheduled the closing of registration to new clients of OpenID 2.0 and OAuth 1.0 on April 30, 2014. (New)
  • Google+ Sign-In can be configured to be OpenID Connect compliant, and we will continue to support OpenID Connect at the protocol level. (Dec. 2013)

Getting user profile information - To consolidate getting user profile information, Google is making the following changes:

This document describes what you must do to migrate your apps so they will continue to operate after services are shut down, and how to best take advantage of the new endpoints listed above.

If you have any questions, please feel free to join our Developing with Google+ community, or tag your Stack Overflow posts with "google-plus" and with "google-oauth" (for OAuth) or "google-openid" (for OpenID 2.0).

Migration timetable (New)

The following table lists sign-in services, endpoints and scopes that Google has deprecated. It lists the dates for shutdowns, end of support, and other restrictions. Modify your apps as noted in the last column. For a service that has a shutdown date, existing app implementations will continue to work until the end of the migration period, at which time the service will be shut down and any calls to it will fail.

Deprecated Service * April 30, 2014 Sept. 1, 2014 April 20, 2015 Developer action
OAuth 2.0 login
(early version)
Google will no longer support this version. In addition, we will remove the undocumented, redundant fields id and cid from the ID token, to conform to the OpenID Connect specification. See the updated ID token fields. Migrate or update OAuth 2.0 login before Sept. 1, 2014.

If necessary, replace ID token field cid with azp and replace id with sub.
userinfo endpoint Google will no longer support the userinfo endpoint service. Migrate to people.get endpoint before Sept. 1, 2014.
https://www.googleapis.com/auth/userinfo.profile scope Google will no longer support this scope. Migrate to the profile or plus.login scope before Sept. 1, 2014.
https://www.googleapis.com/auth/userinfo.email scope Google will no longer support this scope. Migrate to the email scope before Sept. 1, 2014.
OpenID 2.0 API including
OpenID+OAuth hybrid
Google will close registration to new OpenID 2.0 clients. Mapping of OpenID 2.0 identifiers to OAuth 2.0 identifiers will end, and Google will shut down the OpenID 2.0 service. Migrate to Google+ Sign-In before April 20, 2015.
Remaining OAuth 1.0 registration** Consider Migrating to OAuth 2.0

* Deprecated designates a feature that is no longer recommended and should be avoided in favor of some alternate technique. Some deprecated features are shut down after a migration period; others are kept available for backward compatibility.

** General registration for OAuth 1.0 closed in October 2013.

Switch to Google+ Sign-In

If your app authenticates users by any means other than the Google+ Sign-In button, we recommend you switch your app to Google+ Sign-In for its ease of implementation through widgets and client libraries, and support for all users.

Google+ Sign-In provides support for all users with a Google account, even if they have not yet created a Google+ profile. Your app can use the https://www.googleapis.com/auth/plus.login scope or the basic profile scope:

  • https://www.googleapis.com/auth/plus.login scope - Adding the Google+ Sign-In button with the https://www.googleapis.com/auth/plus.login scope gives your app the deepest integration with Google. It provides a simple, secure way to authenticate users. It also enables your app to request permission to access people in the authenticated user's circles, and to write app activities to Google. Users who don't have a Google+ profile will be prompted to create one before they sign in.
  • profile scope - Adding the Google+ Sign-In button with the profile scope provides a simple, secure way to authenticate users with access to only the user's basic information. Users are not prompted to create a Google+ profile.

Both scopes allow for over-the-air Android installs when used with the Google+ Sign-In button.

Migrating sign-in services

You need to migrate your app if it uses any API that Google has deprecated and will be shutting down. Migrating your app can involve both changing how your app signs in users and how it gets user profile information. This section is for apps that do not yet use the Google+ Sign-In button.

The following migration procedures show you how to migrate your sign-in service. Choose the procedure that matches the sign-in service your app currently uses:

If you're already using Google+ Sign-In, and if you use the userinfo endpoint to get email addresses, follow just this procedure:

Migrate or update OAuth 2.0 login

This procedure covers any authentication service that uses the userinfo endpoint, namely OAuth 2.0 login (early version) or OAuth 2.0 login (OpenID Connect). We recommend that you switch to Google+ Sign-In for its widgets and client libraries.

To upgrade to Google+ Sign-In:
  1. Add the sign-in button: Follow the steps for adding a Google+ Sign-In button in your web, Android, or iOS app.

  2. Migrate how your app gets email addresses: If you use the userinfo endpoint to get user email addresses, you must migrate how your app gets email addresses.

To update existing userinfo endpoints and scopes:

Choose this procedure if you prefer to just update your OAuth 2.0 login (OpenID Connect) implementation.

  1. Change endpoint: You must replace the userinfo endpoint with the people.get endpoint by using the following HTTP request path:

    • https://www.googleapis.com/plus/v1/people/me

    If you instead need OpenID Connect format, replace userinfo endpoint with the people.getOpenIdConnect endpoint by using the following HTTP request path:

    • https://www.googleapis.com/plus/v1/people/me/openIdConnect
  2. Change scope: If your app is currently using the https://www.googleapis.com/auth/userinfo.profile scope, you can switch to the profile scope. Your app gets the same profile info that it got before, so your users will not be required to re-consent.

  3. Migrate how your app gets email addresses: If you use the userinfo endpoint to get user email addresses, you must migrate how your app gets email addresses.

Migrate from OpenID 2.0 or OpenID+OAuth hybrid to Google+ Sign-In

If your app is using OpenID 2.0 or OpenID 2.0 + OAuth 1.0 hybrid to authenticate users, you can migrate to Google+ Sign-In as follows:

  1. Add the sign-in button: Follow the steps for adding a Google+ Sign-In button in your web, Android, or iOS app. This procedure includes changing the scopes:

    • If you have only requested the user's email address in the past and expect that to be sufficient in the future, request only the email scope. With this scope, your app will also be able to get basic profile info from users who have upgraded to Google+.
    • If you also want profile information for users who have not yet upgraded to Google+, request the profile scope. Because this scope expands your app's access to user profile information, this scope will require users to re-consent.
    • If you want full integration with Google+ and don't mind that users who don't have a Google+ profile will be prompted to upgrade, request the https://www.googleapis.com/auth/plus.login scope.

  2. Add the OpenID realm: For web apps, configure the Google+ Sign-In button with the data-openidrealm attribute, setting it to the value of the realm that you are currently using for OpenID 2.0. For more details, see step 1 at Migrating to OAuth 2.0 login (OpenID Connect). In that case, data-openidrealm takes care of adjusting the request URI, as described in that document.

  3. Map user IDs - For web apps, map the existing OpenID 2.0 identifier of each user (openid_id) to their new Google+ identifier (sub), as follows.

    1. Retrieve the id_token from the sign-in callback handler. Your server must verify the ID token and associate the openid_id and sub (subject) fields. The openid_id field is only present when data-openidrealm parameter is specified in the sign-in button.

      var idToken = authResult['id_token'];
      if (idToken) {
        // Send the ID token JWT to the server for verification.
      }
      
    2. In your user database, link the openid_id to the new sub ID, and use the new ID going forward as the unique identifier.

  4. Upgrade OAuth 1.0 tokens: For the hybrid case, if you currently store OAuth 1.0 tokens, then you need to upgrade the tokens to OAuth 2.0 by following the steps at Migrating from OAuth 1.0 to OAuth 2.0.

  5. Migrate how your app gets email addresses: If you use the userinfo endpoint to get user email addresses, you must migrate how your app gets email addresses.

Migrating how your app gets email addresses

If your app uses the https://www.googleapis.com/auth/userinfo.email scope or userinfo endpoint to get user email addresses, migrate as follows:

  1. Get or parse the email address: Implement one of the following two options.

    • Get the email address: Replace the userinfo endpoint with people.get. This endpoint returns the Google account email address as the first element of emails[].

    • Parse for the email address: You can save a method call if, instead, you parse the ID token for the email address, as described at Obtain user information from the ID token.

  2. Change scope:

    • If your app is currently using the https://www.googleapis.com/auth/userinfo.email scope, you can switch to the email scope. Your users will not be required to re-consent because your app gets the same email address that it did before.

Notes

Handling errors for Google Apps users

Google+ can be disabled for users who are signed into an enterprise Google Apps account. This includes Google Apps for Business, Education, and Government editions, but not the consumer edition.

Some businesses have policies against the use of social features in apps that are signed into their domain. To enforce this for an enterprise Google Apps account, an administrator can disable Google+ for their signed-in users. Then, when a user initiates sign-in with your app, and if the user consents, they will be signed in with all requested scopes.

Thereafter, if your app makes any calls that fail because the administrator has disabled Google+, the following error is returned:

403 Forbidden

Be sure to handle this error in your code to make sure your app runs smoothly.

An administrator can instead keep Google+ web access enabled but disable Google+ APIs, which means your app cannot make any Google+ calls.

Domain name - The data returned by the people.get method now includes domain, the name of the Google Apps hosted domain that the user is signed into. This value is accessible to your app only for users who consent to either of the email scopes. This property lets your app display the domain name for a user. For example, your app could display a row of user names, each with its domain name. This could help a user select users who are in their own domain.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.