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. Federated Login, based on the OpenID standard, frees users from having to set up separate login accounts for different web sites--and frees web site developers from the task of implementing login authentication 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 integrate Google's Federated Login for a web site or application.
Google supports the OpenID 2.0 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, including 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 and includes favicon support 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.
PAPE (Provider Authentication Policy Extension) allows web developers to request other modifications to the flow, such as asking that Google reprompt the user for their password.
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. For information on Google's other account authorization solutions, see the Getting Started guide.
Note: OpenID authentication now supports Google Apps (hosted) accounts. See OpenID API for Google Apps 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: If the user is already logged into their Google account, or has previously approved automatic login for this web application, the login step or the approval step (or both) may be skipped.
Note: OpenID authentication for Google Apps (hosted) accounts requires an additional discovery step. See OpenID API for Google Apps accounts.
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 keeping the interface as simple as possible. Visit the User Experience summary for Federated Login Google Sites page, where you can find links to demos, mocks and usability research data on how best to present your login process to users.
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 set up as an OpenID relying party. You may also use an implementation provided by a third-party such as JanRain
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.
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 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.
Include the OpenID UI extension parameters to display Google's authentication pages in an alternative user interface, such as a popup window. Design recommendations for the popup window are specified in the user interface extension specification. We support an additional parameter to display your favicon in the OpenID approval page. Your icon is fetched and displayed if you specify openid.ui.icon=true.
Once Google receives confirmation or rejection from the user, if authentication is confirmed it returns a response to the web application. The web application can then close the interface. See the Step 2 open source project to view code for popupManager, a java library to handle this process.
Use the max_auth_age parameter in the PAPE extension to ensure that the login session of the user at Google is recent. You may also specify max_auth_age=0 to force a password reprompt.
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.
Note: 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 exchange user-specific data with a Google service (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 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.
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/authorization 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 making 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 OpenID realm parameter value 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 value of realm. 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), your web application must be able to parse the request token, exchange it for an access token, 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 Signing OAuth Requests.
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 Google may interact with the user to determine the outcome of the request. Valid values are: "checkid_immediate" (No interaction allowed) Google supports an enhacement to checkid_immediate requests via the UI extension. If the request includes "openid.ui.x-has-session", it will be echoed in the response only if Google detects an authenticated session. |
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 (web application) and the identity provider (Google). 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. |
| PAPE extension: | |
openid.ns.pape |
(required) Identifies the extension protocol being used. This value should be "http://specs.openid.net/extensions/pape/1.0". |
openid.pape.max_auth_age |
(optional) Sets the maximum acceptable time (in seconds) since the user last authenticated. If the session is older, the user will be prompted to log in again. Setting the value to zero will force a password reprompt regardless of session age. |
| 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 |
(optional) Specifies the alternative user interface. Currently, the only valid value is "popup". Additional modes may be supported in the future. |
openid.ui.icon |
(optional) Displays the favicon of the referring domain in the OpenID approval page if set to "true". |
openid.ui.x-has-session |
(optional) Used to indicate the presence of an authenticated session in combination with openid.mode="checkid_immediate". |
| 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 |
(optional) Requests the user's home country. This value must be set to "http://axschema.org/contact/country/home". |
openid.ax.type.email |
(optional) 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 |
(optional) Requests the user's first name. This value must be set to "http://axschema.org/namePerson/first". |
openid.ax.type.language |
(optional) Requests the user's preferred language. This value must be set to "http://axschema.org/pref/language". |
openid.ax.type.lastname |
(optional) 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 as query parameters, including a Google-supplied identifier, user information, if requested, and an OAuth request 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.
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 web site or 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 requesting web site.
The example below illustrates a login authentication request as a URL, with an association:
https://www.google.com/accounts/o8/id ?openid.ns=http://specs.openid.net/auth/2.0 &openid.claimed_id=http://specs.openid.net/auth/2.0/identifier_select &openid.identity=http://specs.openid.net/auth/2.0/identifier_select &openid.return_to=http://www.example.com/checkauth &openid.realm=http://www.example.com/ &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup
The example below illustrates a login authentication request, with a maximum session age of 5 minutes, email and language attribute exchange, and a popup UI with favicon support:
https://www.google.com/accounts/o8/id ?openid.ns=http://specs.openid.net/auth/2.0 &openid.ns.pape=http://specs.openid.net/extensions/pape/1.0 &openid.ns.max_auth_age=300 &openid.claimed_id=http://specs.openid.net/auth/2.0/identifier_select &openid.identity=http://specs.openid.net/auth/2.0/identifier_select &openid.return_to=http://www.example.com/checkauth &openid.realm=http://www.example.com/ &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup &openid.ui.ns=http://specs.openid.net/extensions/ui/1.0 &openid.ui.mode=popup &openid.ui.icon=true &openid.ns.ax=http://openid.net/srv/ax/1.0 &openid.ax.mode=fetch_request &openid.ax.type.email=http://axschema.org/contact/email &openid.ax.type.language=http://axschema.org/pref/language &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/id ?openid.ns=http://specs.openid.net/auth/2.0 &openid.claimed_id=http://specs.openid.net/auth/2.0/identifier_select &openid.identity=http://specs.openid.net/auth/2.0/identifier_select &openid.return_to=http://www.example.com/checkauth &openid.realm=http://www.example.com &openid.assoc_handle=ABSmpf6DNMw &openid.mode=checkid_setup &openid.ns.oauth=http://specs.openid.net/extensions/oauth/1.0 &openid.oauth.consumer=www.example.com &openid.oauth.scope=http://docs.google.com/feeds/+http://spreadsheets.google.com/feeds/
The example below illustrates a redirect after a successful user log-in and confirmation:
http://www.example.com/checkauth ?openid.ns=http://specs.openid.net/auth/2.0 &openid.mode=id_res &openid.op_endpoint=https://www.google.com/accounts/o8/ud &openid.response_nonce=2008-09-18T04:14:41Zt6shNlcz-MBdaw &openid.return_to=http://www.example.com:8080/checkauth &openid.assoc_handle=ABSmpf6DNMw &openid.signed=op_endpoint,claimed_id,identity,return_to,response_nonce,assoc_handle &openid.sig=s/gfiWSVLBQcmkjvsKvbIShczH2NOisjzBLZOsfizkI= &openid.identity=https://www.google.com/accounts/o8/id/id=ACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.claimed_id=https://www.google.com/accounts/o8/id/id=ACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_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://specs.openid.net/auth/2.0
The example below illustrates a redirect after a successful user login and confirmation, with time of authentication, email and language information included:
http://www.example.com/8080/checkauth ?openid.ns=http://specs.openid.net/auth/2.0 &openid.mode=id_res &openid.op_endpoint=https://www.google.com/accounts/o8/ud &openid.response_nonce=2008-09-18T04:14:41Zt6shNlcz-MBdaw &openid.return_to=http://www.example.com:8080/checkauth &openid.assoc_handle=ABSmpf6DNMw &openid.ns.pape=http://specs.openid.net/extensions/pape/1.0 &openid.pape.auth_time=2005-05-15T17:11:51Z &openid.pape.auth_policies=http://schemas.openid.net/pape/policies/2007/06/none &openid.signed=op_endpoint,claimed_id,identity,return_to,response_nonce,assoc_handle,ax.mode,ax.type.email,ax.value.email &openid.sig=s/gfiWSVLBQcmkjvsKvbIShczH2NOisjzBLZOsfizkI= &openid.identity=https://www.google.com/accounts/o8/id/id=ACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.claimed_id=https://www.google.com/accounts/o8/id/id=ACyQatixLeLODscWvwqsCXWQ2sa3RRaBhaKTkcsvUElI6tNHIQ1_egX_wt1x3fAY983DpW4UQV_U &openid.ns.ax=http://openid.net/srv/ax/1.0 &openid.ax.mode=fetch_response &openid.ax.type.email=http://axschema.org/contact/email &openid.ax.value.email=fred.example@gmail.com &openid.ax.type.language=http://axschema.org/pref/language &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://specs.openid.net/auth/2.0 &openid.mode=id_res &openid.op_endpoint=https://www.google.com/accounts/o8/ud &openid.response_nonce=2009-01-17T00:11:20ZlJAgbeXUfSSSEA &openid.return_to=http://www.example.com/checkauth &openid.assoc_handle=AOQobUeYs1o3pBTDPsLFdA9AcGKlH &openid.signed=op_endpoint,claimed_id,identity,return_to,response_nonce,assoc_handle,ns.ext2,ext2.consumer,ext2.scope,ext2.request_token &openid.sig=oPvRr++f6%2ul/2ah2nOTg= &openid.identity=https://www.google.com/accounts/o8/id/id=AItOawl27F2M92ry4jTdjiVx06tuFNA &openid.claimed_id=https://www.google.com/accounts/o8/id/id=AItOawl27F2M92ry4jTdjiVx06tuFNA &openid.ns.oauth=http://specs.openid.net/extensions/oauth/1.0 &openid.oauth.scope=http://docs.google.com/feeds/+http://spreadsheets.google.com/feeds/+http://sandbox.gmodules.com/api/ &openid.oauth.request_token=1/fVr0jVubFA83GjYUA
Some US Government websites now accept OpenID logins from a set of vetted OpenID providers. The approved providers support security and privacy features for OpenID formulated by the GSA. These features, known as the GSA OpenID Profile, ensure that OpenID authentication complies with Level of Assurance (LoA) 1, as defined by the US Government Identity, Credential and Access Management (ICAM) initiative.
The Google Accounts OpenID provider supports the GSA OpenID profile. Some of the GSA profile features are available by default and benefit equally all parties that integrate with the Google OpenID provider. Others can be requested by any site on a per-authentication basis by using the OpenID Provider Authentication Policy Extension (PAPE) standard and including specific policy URLs.
Sample request:
openid.ns.pape=http://specs.openid.net/extensions/pape/1.0
openid.pape.max_auth_age=0
openid.pape.preferred_auth_policies=
http://www.idmanagement.gov/schema/2009/05/icam/no-pii.pdf
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
http://www.idmanagement.gov/schema/2009/05/icam/openid-trust-level1.pdf
Sample response:
openid.ns.pape=http://specs.openid.net/extensions/pape/1.0
openid.pape.auth_time=2005-05-15T17:11:51Z
openid.pape.auth_policies=
http://www.idmanagement.gov/schema/2009/05/icam/no-pii.pdf
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
http://www.idmanagement.gov/schema/2009/05/icam/openid-trust-level1.pdf
Each of the policy URLS included in the request can be used independently and cause the OpenID provider to behave in specific ways.
Meaning of each component:
The max_auth_age is used to request password re-entry. It can be used independently of any other policies. For more details, see the PAPE extension request parameters
The inclusion of http://www.idmanagement.gov/schema/2009/05/icam/no-pii.pdf prevents Google from asserting any PII in the response, including but not limited to, email addresses and names.
The inclusion of http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier requires that Google assert different identifiers for each realm for the same user. This is a privacy feature that prevents sites from correlating user activities across different openid realms.
The inclusion of http://www.idmanagement.gov/schema/2009/05/icam/openid-trust-level1.pdf requires Google to assert that the authentication is in compliance with the security requirements of the GSA Profile for OpenID. These security features are provided by default on all Google authentication flows, whether or not this particular policy URL is included.