Migrating to Google Sign-In

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.

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:

  • We deprecated the following userinfo endpoints and scopes as of September 1, 2014 — we will maintain them and keep them available for backward compatibility:
  • We have enhanced and added to the people methods:
    • Enhanced people.get to return user email addresses in the emails array.
    • Enhanced people.get to include the user's domain name.
    • Added the people.getOpenIdConnect endpoint to return profile information in OpenID Connect format.

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, tag your Stack Overflow posts 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 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.

Determining if you need to migrate

If you are unsure whether you must migrate from a deprecated protocol, complete the following steps:

  1. Revoke the access token associated with your application for your user account:
    1. Go to Google's Account Permissions page.
    2. Select your application from the list.
    3. Click Revoke access.
  2. Access your application.
    • If the consent screen includes a deprecation notice, you must migrate to a newer protocol.
    • In addition, you must migrate to a newer protocol if the URL of the consent screen includes any of the following strings: /oauth1, /authsub, /openid2.

Switch to Google Sign-In

If your app authenticates users by any means other than Google Sign-In, 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.

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.
    • If you want only basic profile information, use the fetchBasicProfile feature available on Web and iOS. For other platforms, request the profile scope. Because this scope expands your app's access to user profile information, this scope will require users to re-consent.

  2. Add the OpenID realm: For web apps, configure the Google Sign-In button with the data-openidrealm attribute or openid_realm parameter, 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, the provided OpenID realm 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 or openid_realm 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: