The specification on this page is provided under the following Patent License.
Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
|
English
| Sign in
Third-party web sites and applications can now let visitors sign in using their Google user accounts. The OpenID standard frees users from having to set up separate login accounts for different web sites--and conversely, frees web site developers from the task of managing login information and security measures. OpenID achieves this goal by providing a framework in which users can establish an account with an OpenID provider, such as Google, and use that account to sign into any web site that accepts OpenIDs. This page describes how to enable a web site or application to accept a Google user account for federated login.
Google supports the OpenID 2.0 Directed Identity protocol, providing authentication support as an OpenID provider. On request from a third-party site, Google authenticates users who are signing in with an existing Google account, and returns to the third-party site an identifier that the site can use to recognize the user. This identifier is consistent, enabling the third-party site to recognize the user across multiple sessions. Google also supports the following extensions:
OpenID Attribute Exchange 1.0 allows web developers to access, with the user's approval, certain user information stored with Google, incluing user name and email address.
OpenID User Interface 1.0 supports alternative user experiences for the authentication process. The default experience requires the web application to redirect users away from the application site to Google's authentication pages. This extension allows web developers to open Google authentication in a popup window for a smoother experience.
OpenID+OAuth Hybrid protocol lets web developers combine an OpenID request with an OAuth authentication request. This extension is useful for web developers who use both OpenID and OAuth, particularly in that it simplifies the process for users by requesting their approval once instead of twice.
For more information on the OpenID framework, refer to the following specifications:
See also the Google Group on Federated Login for discussion on using Google's OpenID API.
Note: OpenID authentication is currently supported for Google accounts only, not Google Apps (hosted) accounts.
This document is for developers who want to equip their web applications to accept Google login authentication. It assumes you've read up on the OpenID protocol and are familiar with terminology and the requirements for setting up as an OpenID relying party.
This section provides a high-level overview of how OpenID authentication works from all perspectives.
OpenID login authentication for web applications involves a sequence of interactions between your web application, Google's login authentication service, and the end user. The diagram and sequence below describe the process as recommended by Google.
Note: In some circumstances the login step or the approval step (or both) may be skipped.
The following sequence describes the user's authentication experience in detail:
Note: Both the login and user information sharing must be approved by the user for authentication to continue. The user does not have the option of approving one but not the other.
This section covers topics relevant to using Google's login authentication with OpenID. Join Google Group on Federated Login for discussion on using Google's OpenID API.
We recommend an interface that lets the user select from a group of trusted identity providers, rather than requiring the user to supply some identity which is then used to "discover" the user's login preference. For interface design suggestions, see "Designing a Login User Interface".
There are libraries available for Java Python, PHP, and others. Google authentication has been tested against the OpenID for Java library; see also libraries at OpenID Enabled. A comprehensive list of libraries is available on the OpenID site. For developers using OpenID for Java, this quick-start guide covers how to implement a relying party.
Send discovery requests to the discovery target URL (see the OpenID endpoint reference) to retrieve a valid XRDS document containing the Google OpenID endpoint. Use an OpenID library or send GET or POST requests directly as specified in the endpoint reference. If you're using OpenID for Java, the variable userSuppliedString should be set to the discovery target.
After receiving the Google OpenID endpoint, use the values specified in the endpoint reference to construct and send login authentication requests. The value for openid.return_to can include URLs with query parameters. When setting the openid.realm parameter, keep in mind that user identifiers returned by Google are keyed to the realm value, in combination with the user's login. This means if your application begins referencing a different realm, the user IDs Google returns will be different, and your application will not be able to recognize returning users.
Include the attribute exchange parameters to authentication requests to access user information (such as name and email) as well as their login ID.
When including the attribute exchange parameters in an authentication request, keep in mind that the parameter names do not need to match those listed in the OpenID endpoint reference. Google uses the namespace aliases "ax" for these parameters but you can specify any alias you choose (openid.ns.<alias>). OpenID libraries construct requests using their own namespaces. The critical issue is that the values of these parameters be set to the strings specified in the endpoint reference.
Note: If you request an attribute and none is returned, it may be because the user has previously authorized revealing this attribute to your site and requested that Google auto-approve requests for your site. Google expects third-party applications to store user attributes; because of privacy considerations related to requests approved without user interaction, attributes previously released to your site will not be sent again. If you request a new attribute type, or the value for the user attribute has changed since it was disclosed to your site, the user will be prompted to authorize sending the requested attribute.
Include the OAuth parameters to simultaneously request login authentication and get an authentication token to access the user's Google service data with OAuth. For more detailed help on using this feature, see Implementing OAuth with OpenID.
On successful authentication, the user is redirected from the Google authentication page back to the third-party application, with query parameters containing:
Note: If you request an OAuth token and none is returned, if may be because you've previously acquired an access token keyed to the specific user and scope. For privacy considerations, Google expects third-party applications to store OAuth tokens, which are long-lived, rather than request a new token every time the application needs to access the user's Google service.
You can design your federated login page in any way that fits your site; the page simply needs to (1) solicit information from the user about how they want to sign in, and (2) trigger the sign-in process. The traditional OpenID specification called for a login box or other text entry field that required the user to supply some kind of identifier. For Google's directed identity approach, we recommend any of the following options:
We recommend keeping the interface as simple as possible. See this usability research on federated login interfaces for insight on developing an effective interface.
Note: Federated login authentication is currently not supported for Google Apps (hosted) accounts. See the OAuth documentation for implementing OAuth without OpenID.
The goal of OAuth is to acquire an access token from Google, which can then be used to access a user's Google service data (such as calendar information or an address book). The regular OAuth process is a four-step sequence: (1) ask for a "request" token, (2) ask for the token to be authorized, which triggers user approval, (3) exchange the authorized request token for an "access" token, and (4) use the access token to interact with the user's Google service data. For a more detailed description, see OAuth Authentication for Web Applications.
With OpenID+OAuth, this sequence remains essentially the same. The difference is that getting an authorized OAuth request token (steps 1 and 2) is wrapped up in the OpenID authentication request. In this way, the user can approve login and service access at the same time. Once a request token is acquired, your application must still perform steps 3 and 4 of the OAuth process.
See a demo of OpenID+OAuth in action (with source code). The demo illustrates the simplicity of a combined user interface doing double duty: view a page requesting sign-on approval and access to your Google Docs and Spreadsheets services, click "Continue Sign-in", and voila: you're logged into the site and viewing a list of all your Google docs. All the authentication is happening behind the scenes, while the cost to the user is one page view and one click.
Use the automated interface to register your domain, keeping in mind that the registered domain must be consistent with the realm parameter being used with OpenID. For example, the domain "www.somedomain.com" is consistent with a realm of "http://*.somedomain.com". You also need to set up a method for signing requests using one of the two supported signature methods; you'll need to use the consumer key and secret when OAuth requests.
Note: If you've been using both OpenID and OAuth separately, you may be able to use the same domain registration as long as the realm parameter value used with OpenID matches the OAuth consumer parameter value. If the values don't match, either re-register a domain consistent with the OpenID realm value, or change the realm value. However, changing the realm may not be a viable option if you have existing users with OpenID.
Implement OpenID as described in Setting Up OpenID.
The response from an OpenID request contains an authorized request token as a query parameter. Whether you use an OAuth library or manage requests manually (see Setting Up OAuth), the web application must be able to parse the request token, exchange it, and store the access token for future use. See the OAuthGetAccessToken endpoint for information on exchanging a request token for an access token. All OAuth requests need to be signed using the consumer key and secret, acquired during registration.
See documentation on the Google service for help on the proper request format. All requests to a Google service must include a valid OAuth access token and be signed. Generally, a request to a Google service will be in the form of an HTTP GET (or POST if writing new data), with access token and signature referenced in the request header.
This section contains a comprehensive reference of the OpenID endpoint. See "Working with OpenID" for help implementing a federated login solution using an OpenID-compliant library.
To get the Google OpenID endpoint, perform discovery by sending either a GET or HEAD HTTP request to https://www.google.com/accounts/o8/id. When using a GET, we recommend setting the Accept header to "application/xrds+xml". Google returns an XRDS document containing an OpenID provider endpoint URL.The endpoint address is annotated as:
<Service priority="0">
<Type>http://specs.openid.net/auth/2.0/server</Type>
<URI>{Google's login endpoint URI}</URI>
</Service>
Once you've acquired the Google endpoint, send authentication requests to it, specifying the following parameters as relevant. Connect to the endpoint by sending a request to the URL or by making an HTTP POST request.
| Parameter | Description |
|---|---|
openid.mode |
(required) Interaction mode. Specifies whether the type of interaction allowed between end user and the identity provider is synchronous or asynchronous. Valid values are: "checkid_immediate" (synchronous) |
openid.ns |
(required) Protocol version. Value identifying the OpenID protocol version being used. This value should be "http://specs.openid.net/auth/2.0". |
openid.return_to |
(required) Return URL. Value indicating the URL where the user should be returned to after signing in. Google supports HTTP and HTTPS address types; addresses that differ only in HTTP or HTTPS are considered the same address. |
openid.assoc_handle |
(optional) Association handle. Set if an association was established between the relying party and the identity provider. See OpenID specification Section 8. |
openid.claimed_id |
(optional) Claimed identifier. This value must be set to "http://specs.openid.net/auth/2.0/identifier_select". |
openid.identity |
(optional) Alternate identifier. This value must be set to "http://specs.openid.net/auth/2.0/identifier_select". |
openid.realm |
(optional) Authenticated realm. Identifies the domain that the end user is being asked to trust. (Example: "http://*.myexamplesite.com") This value must be consistent with the domain defined in openid.return_to. If this parameter is not defined, Google will use the URL referenced in openid.return_to. The value of realm is used on the Google Federated Login page to identify the requesting site to the user. It is also used to determine the value of the persistent user ID returned by Google. |
| User interface extension: | |
openid.ns.ui |
(required) Indicates that the OpenID provider's authentication pages will be displayed in an alternative user interface This parameter must be set to "http://specs.openid.net/extensions/ui/1.0". |
openid.ui.mode |
(required) Specifies the alternative user interface. Currently, the only valid value is "popup". Additional modes may be supported in the future. |
| Attribute exchange extension: | |
openid.ns.ax |
(required) Indicates request for user attribute information. This value must be set to "http://openid.net/srv/ax/1.0". |
openid.ax.mode |
(required) This value must be set to "fetch_request". |
openid.ax.required |
(required) Specifies the attribute being requested. Valid values include: |
openid.ax.type.country |
(required) Requests the user's home country. This value must be set to "http://axschema.org/contact/country/home". |
openid.ax.type.email |
(required) Requests the user's gmail address. This value must be set to either "http://axschema.org/contact/email" or "http://schema.openid.net/contact/email". |
openid.ax.type.firstname |
(required) Requests the user's first name. This value must be set to "http://axschema.org/namePerson/first". |
openid.ax.type.language |
(required) Requests the user's preferred language. This value must be set to "http://axschema.org/pref/language". |
openid.ax.type.lastname |
(required) Requests the user's last name. This value must be set to "http://axschema.org/namePerson/last". |
| OAuth extension: | |
openid.ns.ext2 |
(required) Indicates request for an OAuth token. This value must be set to "http://specs.openid.net/extensions/oauth/1.0" |
openid.ext2.consumer |
(required) Consumer key provided by Google after registering the site. This is typically a DNS domain name. Must be consistent with the value for realm (for example, realm = "http://www.example.com" and ext2.consumer = "www.example.com", or realm = "http://*.somedomain.com and ext2.consumer = "www.somedomain.com"). |
openid.ext2.scope |
(required) List of URLs identifying the Google service(s) to be accessed. See documentation for the services of interest to get the appropriate scope values. Lists of two or more scopes must be space-delimited and properly escaped. This parameter is not defined in the OAuth standards; it is a Google-specific parameter. |
Note: The extension parameter names shown here (for attribute exchange and OAuth) use namespace aliases, such as "ax", for convenience only. OpenID libraries specify their own namespaces. Google authentication will recognize the parameters if the values are set correctly, regardless of name.
Once Google accepts the authentication request, the user is redirected to a Google authentication page. At this point the authentication sequence takes over. On successful authentication, Google redirects the user back to the URL specified in the openid.return_to parameter of the original request. Response data is appended a query parameters, including a Google-supplied identifier, user information, if requested, and a OAuthrequest token, if requested.
The Google-supplied identifier, which has no connection to the user's actual Google account name or password, is a persistent value; it remains constant even if the user changes their Google user name and/or email address. This identifier is also a "directed identity", that is, Google returns a different value to each relying party. Google uses the request parameter openid.realm to recognize the relying party, so if the third-party application decides to change this value, all user identifiers will change.
For security and privacy reasons, Google does not return the user's email address with every successful request. If the user selects the automatic login option on the Google sign-in page, Google does not return the address for subsequent login requests unless the user has made changes to their address.
Google may redirect through an HTTP 302 response code to the return URL, resulting in a GET request, or may cause the browser to issue a POST request to the return URL, passing the OpenID parameters in the POST body. A relying party application should be prepared to accept responses as both GETs and POSTs.
If the user doesn't approve the authentication request, Google sends a negative assertion to the relying party.
The example below illustrates a login authentication request as a URL, with an association:
https://www.google.com/accounts/o8/ud ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.return_to=http%3A%2F%2Fwww.example.com%2Fcheckauth &openid.realm=http%3A%2F%2Fwww.example.com%2F &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup
The example below illustrates a login authentication request, with email and language attribute exchange, and a popup UI:
https://www.google.com/accounts/o8/ud ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.return_to=http%3A%2F%2Fwww.example.com%2Fcheckauth &openid.realm=http%3A%2F%2Fwww.example.com%2F &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup openid.ui.ns=htt%3A%2F%2Fspecs.openid.net%2Fextensions%2Fui%2F1.0 openid.ui.mode=popup &openid.ns.ax=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0 &openid.ax.mode=fetch_request &openid.ax.type.email=http%3A%2F%2Faxschema.org%2Fcontact%2Femail &openid.ax.type.language=http%3A%2F%2Faxschema.org%2Fpref%2Flanguage &openid.ax.required=email,language
The example below illustrates an OpenID+OAuth hybrid request. The OAuth extension requests access to the user's Google Docs and Spreadsheets data. Notice that this example uses the namespace "oauth" in place of "ext2":
https://www.google.com/accounts/o8/ud ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select &openid.return_to=http%3A%2F%2Fwww.example.com%2Fcheckauth &openid.realm=http%3A%2F%2Fwww.example.com &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup &openid.ns.oauth=http%3A%2F%2Fspecs.openid.net%2Fextensions%2Foauth%2F1.0 &openid.oauth.consumer=www.example.com &openid.oauth.scope=http%3A%2F%2Fdocs.google.com%2Ffeeds%2F+http%3A%2F%2Fspreadsheets.google.com%2Ffeeds%2F
The example below illustrates a redirect after a successful user log-in and confirmation:
http://www.example.com/checkauth ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.mode=id_res &openid.op_endpoint=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fud &openid.response_nonce=2008-09-18T04%3A14%3A41Zt6shNlcz-MBdaw &openid.return_to=http%3A%2F%2Fwww.example.com%3A8080%2Fcheckauth &openid.assoc_handle=ABSmpf6DNMw &openid.signed=op_endpoint%2Cclaimed_id%2Cidentity%2Creturn_to%2Cresponse_nonce%2Cassoc_handle &openid.sig=s%2FgfiWSVLBQcmkjvsKvbIShczH2NOisjzBLZOsfizkI%3D &openid.identity=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.claimed_id=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U
The example below illustrates a redirect after an unsuccessful log-in or if the user has declined to approve authentication:
http://www.example.com/checkauth ?openid.mode=cancel &openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0
The example below illustrates a redirect after a successful user login and confirmation, with email and language information included:
http://www.example.com:8080/checkauth ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.mode=id_res &openid.op_endpoint=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fud &openid.response_nonce=2008-09-18T04%3A14%3A41Zt6shNlcz-MBdaw &openid.return_to=http%3A%2F%2Fwww.example.com%3A8080%2Fcheckauth &openid.assoc_handle=ABSmpf6DNMw &openid.signed=op_endpoint%2Cclaimed_id%2Cidentity%2Creturn_to%2Cresponse_nonce%2Cassoc_handle%2Cax.mode%2Cax.type.email%2Cax.value.email &openid.sig=s%2FgfiWSVLBQcmkjvsKvbIShczH2NOisjzBLZOsfizkI%3D &openid.identity=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.claimed_id=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.ns.ax=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0 &openid.ax.mode=fetch_response &openid.ax.type.email=http%3A%2F%2Faxschema.org%2Fcontact%2Femail &openid.ax.value.email=fred.example%40gmail.com &openid.ax.type.language=http%3A%2F%2Faxschema.org%2Fpref%2Flanguage &openid.ax.value.language=english
The example below illustrates a redirect after a successful user login and confirmation, with an authorized OAuth request token included:
http://www.example.com/checkauth ?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0 &openid.mode=id_res &openid.op_endpoint=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fud &openid.response_nonce=2009-01-17T00%3A11%3A20ZlJAgbeXUfSSSEA &openid.return_to=http%3A%2F%2Fwww.example.com%2Fcheckauth &openid.assoc_handle=AOQobUeYs1o3pBTDPsLFdA9AcGKlH &openid.signed=op_endpoint%2Cclaimed_id%2Cidentity%2Creturn_to%2Cresponse_nonce%2Cassoc_handle%2Cns.ext2%2Cext2.consumer%2Cext2.scope%2Cext2.request_token &openid.sig=oPvRr%2B%2Bf6%2ul%2F2ah2nOTg%3D &openid.identity=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DAItOawl27F2M92ry4jTdjiVx06tuFNA &openid.claimed_id=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid%3Fid%3DAItOawl27F2M92ry4jTdjiVx06tuFNA &openid.ns.oauth=http%3A%2F%2Fspecs.openid.net%2Fextensions%2Foauth%2F1.0 &openid.oauth.scope=http%3A%2F%2Fdocs.google.com%2Ffeeds%2F+http%3A%2F%2Fspreadsheets.google.com%2Ffeeds%2F+http%3A%2F%2Fsandbox.gmodules.com%2Fapi%2F &openid.oauth.request_token=1%2FfVr0jVubFA83GjYUA