OpenID 2.0 (Migration)

Important: Google has deprecated OpenID 2.0 and
will shut it down after a migration period. If your app uses OpenID 2.0, you must
migrate your app by the shutdown date April 20, 2015, as shown in the
migration timetable.
Note: If you are looking for documentation for web applications that use the deprecated OpenID 2.0 for Google login,
see OpenID 2.0 (Deprecated).
For information about using the deprecated OpenID 2.0 authentication with Google Apps (hosted) accounts, see
OpenID API for Google Apps accounts (Deprecated).
Note: To get help on Stack Overflow with migrating your OpenID 2.0 app, tag your questions with 'google-openid'.

This document provides details about migrating your code from OpenID 2.0 to OpenID Connect.
We recommend you use Google+ Sign-in, which is our client library that provides OpenID Connect sign-in for Google Accounts.
You can also use our OpenID Connect (OAuth 2.0 for Login) endpoints directly. This document provides information about both migration strategies.

Contents

OpenID 2.0 Shutdown Timetable

OpenID 2.0 for Google accounts is going away (it has been superseded by OpenID Connect). As there is no developer registration in OpenID 2.0 and we have no way to alert developers to this fact, we are making user-visible changes to the OpenID 2.0 approval page. So that more people see this page, we will also slowly turn-down the auto-approval feature as the deadline approaches. Please complete your migration to OpenID Connect or Google+ Sign-in before the shutdown date.

You can delay these user-visible changes for a short time by adding the following parameter:
&openid_shutdown_ack=2015-04-20 to the OpenID 2.0 request,
which acknowledges to us that you are aware of the shutdown timetable, and are planning your migration.

Schedule for user-visible changes to the approval page:

November 18, 2014: User-facing warning message may be shown on consent dialogs, directing users to this help article. Developers may suppress deprecation warnings by adding the openid_shutdown_ack parameter, as specified above.

December 1, 2014: Auto-approval is disabled for a small number of requests on an intermittent basis, some users will be forced to re-consent.

January 12, 2015: Auto-approval is progressivly disabled for more and more users, these users will be forced to re-consent. Developers passing openid_shutdown_ack are unaffected.

February 23, 2015: Auto-approval is turned off, users must consent on each request. Developers passing openid_shutdown_ack are unaffected.

March 23, 2015: Grace period for developers using the openid_shutdown_ack parameter ends, warning is shown and auto-approval turned off for all applications.

April 20, 2015: OpenID 2.0 is shut down. A static error page will be displayed on all requests. Make sure you have migrated well before this date.

Migrating to Google+ Sign-In

If you provide a "sign-in with Google" feature, we recommend using
Google+
Sign-In. Google+ Sign-In provides OAuth 2.0 (OpenID Connect) authentication with rich social
features and access to additional Google desktop and mobile features. Google+ Sign-In supports transparent migration
and offers widgets and client libraries that make it easy to implement. It
supports all users who have a Google account, whether or not they've upgraded to Google+.

If you currently have
OpenID 2.0–based software in production, or if you have users who are known only by
an OpenID 2.0 identifier, you can switch to Google+ Sign-In without losing track of your existing
users by linking the OpenID 2.0 account identifiers to new Google+ Sign-In identifiers, then using
the new identifiers going forward. For details, see the step-by-step instructions for
switching from OpenID 2.0 to Google+ Sign-In.

If you switch to Google+ Sign-In, here are some tips:

If users have provided email
addresses to your app via OpenID 2.0 and you do not want these users to be asked to re-consent
when you switch to Google+ Sign-In, use only the email scope.

To configure Google+ Sign-In to return profile information in OpenID Connect format, use the
openid scope and get the user profile by calling the
people.getOpenIdConnect endpoint.

If your OpenID 2.0–based app does not need social features or is on a platform not supported by Google+
Sign-In, or if you want to work directly with the OAuth 2.0 REST APIs, then we recommend migrating
to Google's OpenID Connect (OAuth 2.0 for login) solution, as described below.

Migrating to OpenID Connect (OAuth 2.0 for login)

The basic techniques for logging in with OpenID Connect are described in
Using OAuth 2.0 for Login (OpenID Connect). You can introduce OpenID
Connect–based authentication into your OpenID 2.0 authentication process without losing track
of existing users' accounts by following these steps:

Step 1: Adjust the authentication request URI that you send to Google
by adding openid.realm and other parameters.

Note: Support for the OpenID 2.0 identifier mapping described above will remain in effect until January 1, 2017.

Step 1: Adjust the authentication request URI that you send to Google

When you construct
an authentication request to send to Google, it is in the form of a URI that begins with
Google's OAuth 2.0 endpoint, https://accounts.google.com/o/oauth2/auth. You construct
the rest of the URI by adding parameters as needed. For applications that use OpenID 2.0, the
authentication request URI may include an openid.realm parameter, and can also include
the login_hint and other parameters.

If you are migrating your code from OpenID 2.0, set up your OpenID Connect authentication
requests as follows:

In the Developers Console, find your application's redirect_uri and change it (if
necessary) so that it matches your OpenID 2.0 openid.realm value, according to the matching
rules in section 9.2 of
the OpenID 2.0 spec.

To find the redirect URIs for your OAuth 2.0 credentials, do the following:

You can modify the list of redirect URIs by clicking Edit settings below the table, or by
deleting and recreating your credential.

When you construct your OpenID Connect authentication URI, include an extra argument,
the openid.realm parameter. Use the same value that you used
for the openid.realm parameter in your OpenID 2.0 requests.

You must also include a scope parameter that requests access to the user ID. We recommend using
the email scope,
which allows your app to get basic profile information from users who have upgraded to Google+.
In some situations when you use the email scope, users
are not required to re-consent. The user is not presented with a consent screen if all the following are true:

The user has provided an email address to your application via OpenID 2.0, and

You request only the email scope, and

The access type for your request is online, which is the default.
(Note that when OpenID access is granted, it is always for online access, so a refresh token cannot be
returned from these requests. For more about access_type, see
Authentication URI parameters.)

If these three conditions are met, the user's account information is migrated
to the email scope.

Instead of the email scope, you can specify profile or plus.login.
The profile scope allows your app to get some profile information for users who
have not yet upgraded to Google+, but because it expands your app's access to user data, this
scope will require users to re-consent. The plus.login
scope gives you access to write to the user's history and see the people in their circles.

If you know the user's email address, include
it in the authentication URI as the value of the login_hint parameter.
If you do not include a login_hint and the user is signed into Google with multiple
accounts, they will see an "account chooser" asking them to select one account. This might be
surprising to them, and they might select an account other than the one your application is trying
to authorize, which could increase the complexity of your task.

Step 3: Map OpenID 2.0 identifiers to OpenID Connect identifiers

When you send an OpenID Connect authentication request URI to Google as described in Step 1, you include
an openid.realm parameter. The response that is sent to your redirect_uri includes
an authorization code that your application can use to
retrieve an access token and an ID token. (You can also retrieve an ID token
directly from the OpenID Connect authentication request by adding id_token to the
response_type parameter, potentially saving a back-end call to the token endpoint.)

The
response from that token request includes the usual fields (access_token, etc.),
plus an openid_id field and
the standard OpenID Connect sub field. The fields you need in this context are
openid_id and sub:

The openid_id field holds the OpenID 2.0 identifier. OpenID 2.0 identifiers are
strings that begin with https://www.google.com/accounts/o8/id?id=.

The sub field holds the OpenID Connect identifier (which
corresponds to the id field of the Google+ people.get
response). OpenID Connect identifiers are long numeric strings such as 1016730112881507946.

To migrate your sign-in infrastructure from OpenID 2.0 to OpenID Connect, add code to your
application that does the following for each response that you receive from a
token request:

Extract the sub field from the token-request response. This is the
OpenID Connect identifier.

In your user database, link the openid_id to the new sub ID.

Use the new IDs going forward.

Tip: If you overwrite a user's OpenID 2.0 identifier (openid_id) and
need to find it again, you can repeat the process of including an openid.realm
parameter in an authentication request and mapping the returned openid_id to the
new sub ID.