Click here to see your recently viewed pages and most viewed pages.
Hide
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).

The next section describes specific details about these changes.

Changes

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

  • We have deprecated OpenID 2.0 and will shut it down on April 20, 2015, after a migration period.
  • We closed registration to new clients of OpenID 2.0 and OAuth 1.0 in May 2014.
  • Google+ Sign-In can be configured to be OpenID Connect compliant, and we will continue to support OpenID Connect at the protocol level.

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

This document describes what you must do to update or migrate your apps so they will continue to operate after services are shut down. It also recommends best practices 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

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 * May 19, 2014 September 1, 2014 April 20, 2015 Developer action
userinfo endpoint Deprecated* and will be maintained and kept available for backward compatibility.

Google will continue generating new tokens with these scopes.
Consider migrating to people.get endpoint
https://www.googleapis.com/auth/userinfo.profile scope Consider migrating to the profile or plus.login scope
https://www.googleapis.com/auth/userinfo.email scope Consider migrating to the email scope
OpenID 2.0 API including
OpenID+OAuth hybrid
Deprecated.*
Google closed registration to new OpenID 2.0 clients.
Google shuts down the OpenID 2.0 service.**

However, mapping of OpenID 2.0 identifiers to OAuth 2.0 identifiers will continue to work until January 1, 2017.
Migrate to Google+ Sign-In before April 20, 2015.**
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 the prescribed alternate technique. Some deprecated features are shut down after a migration period, such as OpenID 2.0; others, such as userinfo and OAuth 2.0 login (early version) are maintained and kept available for backward compatibility.

** Prior to the shutdown date, we will be showing user-visible notices on the approval (user consent) page. Read the OpenID 2.0 migration documentation for the detailed schedule of user-visible changes and how you can temporarily suppress these notices.

*** Google closed general registration to new OAuth 1.0 clients 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, as described in the following sections, 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 either prompt those users to create a Google+ profile (by using the https://www.googleapis.com/auth/plus.login scope) or not (by using the profile scope), as follows:

  • 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.

If your app is already using Google+ Sign-In and uses the deprecated userinfo endpoint to get email addresses, follow just this procedure:

Updating or migrating sign-in services

This section is for apps that do not use the Google+ Sign-In button. You can update or migrate your sign-in service:

  • Updating means making minimal changes to your existing code by moving to the closest non-deprecated scopes or endpoints.
  • Migrating means switching to a different sign-in service. You must migrate your app if it uses any API that Google has deprecated and will be shutting down.

The following procedures show you how to update or migrate your sign-in service. They involve both changing how your app signs in users and how gets user profile information. Choose the procedure that matches the sign-in service your app currently uses:

Update OAuth 2.0 login or migrate to Google+ Sign-In

This procedure covers any authentication service that uses the userinfo endpoint. We recommend that you migrate to Google+ Sign-In for its widgets and client libraries.

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: (Optional) We recommend you replace the deprecated 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 the deprecated 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, we recommend you 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. Update how your app gets email addresses: If you use the deprecated userinfo endpoint to get user email addresses, we recommend you update how your app gets email addresses.

To migrate 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. Update how your app gets email addresses: If you use the deprecated userinfo endpoint to get user email addresses, we recommend you update 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. Update how your app gets email addresses: If you use the deprecated userinfo endpoint to get user email addresses, we recommend you update how your app gets email addresses.

Updating how your app gets email addresses

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

  1. Update the scope:

    • If your app is currently using the deprecated https://www.googleapis.com/auth/userinfo.email scope, we recommend you 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.
  2. Update the endpoint: Use one of the following options.

    • Continue using the userinfo endpoint. Consider using either of the following two options, as they are not deprecated.

    • Get the email address: Replace the deprecated userinfo endpoint with people.get. This endpoint returns the Google account email address as the first element of emails[]. Your users will not be required to re-consent because the array will contain only the email address for the Google account.

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

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.