If you need information about creating an OpenID 2.0–based web application that accepts Google login authentication, see OpenID 2.0 (Deprecated). For information about using OpenID 2.0 authentication with Google Apps (hosted) accounts, see OpenID API for Google Apps accounts.
This document provides details about updating your code away from OpenID 2.0. The first section describes why you might want to switch to Google+ Sign-In and gives a few tips on switching. If you cannot switch to Google+ Sign-In or do not want to, the rest of this document provides step-by-step instructions for updating an OpenID 2.0 authentication process to use OAuth 2.0 (OpenID Connect).
- About Google+ Sign-In
- Migrating to OAuth 2.0 login (OpenID Connect)
- Migrating a hybrid login solution
- Migrating how your app gets email addresses
About 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
- To configure Google+ Sign-In to return profile information in OpenID Connect format, use the
openidscope and get the user profile by calling the
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 OAuth 2.0 login (OpenID Connect) solution, as described below.
Migrating to OAuth 2.0 login (OpenID Connect)
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
openid.realmand other parameters.
- Step 2: Update your sign-in code to use an OpenID Connect authentication process.
- Step 3: Map existing OpenID 2.0 identifiers to new OpenID Connect identifiers and add the new identifiers to your user database.
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
login_hint and other parameters.
If you are migrating your code from OpenID 2.0, set up your OpenID Connect authentication requests as follows:
- If you have not yet done so, obtain OAuth 2.0 credentials for your project from the Google Developers Console.
In the Developers Console, find your application's
redirect_uriand change it (if necessary) so that it matches your OpenID 2.0
openid.realmvalue, according to the matching rules in section 9.2 of the OpenID 2.0 spec.
To find your project's redirect URI, do the following:
- Go to the Google Developers Console.
- Select a project.
- In the sidebar on the left, select APIs & auth. In the displayed list of APIs, make sure all the APIs you are using show a status of ON.
- In the sidebar on the left, select Credentials.
- Find the line labeled Redirect URIs. If there are no redirect URIs, then create them by selecting Create New Client ID.
When you construct your OpenID Connect authentication URI, include an extra argument, the
openid.realmparameter. Use the same value that you used for the
openid.realmparameter in your OpenID 2.0 requests.
You must also include a scope parameter that requests access to the user ID. We recommend using the
- The user has provided an email address to your application via OpenID 2.0, and
- You request only the
- 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
Instead of the
profilescope 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.loginscope 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_hintparameter. If you do not include a
login_hintand 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 2: Update your sign-in code
Update your sign-in code so that it launches an OpenID Connect authentication process instead of an OpenID 2.0 authentication process:
- Use the
people.getOpenIdConnectendpoint, either by using the following HTTP request path, or by using the corresponding client library call:
- No change is needed to the OpenID Connect scopes
The response includes basic user data in the OpenID Connect format.
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
openid.realm parameter. The response that is sent to your
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.)
response from that token request includes the usual fields (
openid_id field and
the standard OpenID Connect
sub field. The fields you need in this context are
openid_idfield holds the OpenID 2.0 identifier. OpenID 2.0 identifiers are strings that begin with
subfield holds the OpenID Connect identifier (which corresponds to the
idfield of the Google+
people.getresponse). OpenID Connect identifiers are long numeric strings such as
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
subfield from the token-request response. This is the OpenID Connect identifier.
- In your user database, link the
openid_idto the new
- Use the new IDs going forward.
Migrating a hybrid login solution
If your app uses a hybrid OpenID 2.0 / OAuth 1.0 login solution, you must migrate your app by the deadlines given in the migration timetable. We recommend that you switch to Google+ Sign-In. For step-by-step instructions, see Migrate from OpenID 2.0 or OpenID+OAuth hybrid to Google+ Sign-In.
If for some reason you need to work directly with the OpenID Connect OAuth 2.0 protocols, it is possible to migrate the two components of your app separately:
- To migrate from OpenID 2.0 to OpenID Connect, see Migrating to OAuth 2.0 login (OpenID Connect).
- To migrate from OAuth 1.0 to OAuth 2.0, see Migrating from OAuth 1.0 to OAuth 2.0.
The general information in Implementing OAuth with federated login (hybrid protocol) still applies.
Migrating how your app gets email addresses
If you use the deprecated
userinfo endpoint to get user email addresses, you must
migrate how your app gets email addresses.