OpenID Connect

Google's OpenID Connect endpoint is OpenID Certified.

Google's OAuth 2.0 APIs can be used for both authentication and authorization. This document describes our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification, and is OpenID Certified. The documentation found in Using OAuth 2.0 to Access Google APIs also applies to this service. If you want to explore this protocol interactively, we recommend the Google OAuth 2.0 Playground. To get help on Stack Overflow, tag your questions with 'google-oauth'.

Setting up OAuth 2.0

Before your application can use Google's OAuth 2.0 authentication system for user login, you must set up a project in the Google Developers Console to obtain OAuth 2.0 credentials, set a redirect URI, and (optionally) customize the branding information that your users see on the user-consent screen. You can also use the Developers Console to create a service account, enable billing, set up filtering, and do other tasks. For more details, see the Google Developers Console Help.

Obtain OAuth 2.0 credentials

You need OAuth 2.0 credentials, including a client ID and client secret, to authenticate users and gain access to Google's APIs.

To find your project's client ID and client secret, do the following:

  1. Select an existing OAuth 2.0 credential or open the Credentials page.
  2. If you haven't done so already, create your project's OAuth 2.0 credentials by clicking Add credentials > OAuth 2.0 client ID, and providing the information needed to create the credentials.
  3. Look for the Client ID in the OAuth 2.0 client IDs section. You can click the client ID for details.

Set a redirect URI

The redirect URI that you set in the Developers Console determines where Google sends responses to your authentication requests.

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

  1. Open the Credentials page.
  2. If you haven't done so already, create your OAuth 2.0 credentials by clicking Add credentials > OAuth 2.0 client ID.
  3. After you create your credentials, view or edit the redirect URLs by clicking the client ID in the OAuth 2.0 client IDs section.

Customize the user consent screen

For your users, the OAuth 2.0 authentication experience includes a consent screen that describes the information that the user is releasing and the terms that apply. For example, when the user logs in, they might be asked to give your app access to their email address and basic account information. You request access to this information using the scope parameter, which your app includes in its authentication request. You can also use scopes to request access to other Google APIs.

The user consent screen also presents branding information such as your product name, logo, and a homepage URL. You control the branding information in the Developers Console.

To set up your project's consent screen, do the following:

  1. Open the Consent Screen page in the Google Developers Console. If prompted, select a project or create a new one.
  2. Fill out the form and click Save.

The following consent dialog shows what a user would see when a combination of OAuth 2.0 and Google Drive scopes are present in the request. (This generic dialog was generated using the Google OAuth 2.0 Playground, so it does not include branding information that would be set in the Developers Console.)

Consent page screen shot

Accessing the service

Google and third parties provide libraries that you can use to take care of many of the implementation details of authenticating users and gaining access to Google APIs. Examples include Google Sign-In and the Google client libraries, which are available for a variety of platforms.

If you choose not to use a library, follow the instructions in the remainder of this document, which describes the HTTP request flows that underly the available libraries.

Authenticating the user

Authenticating the user involves obtaining an ID token and validating it. ID tokens are a standardized feature of OpenID Connect designed for use in sharing identity assertions on the Internet.

The most commonly used approaches for authenticating a user and obtaining an ID token are called the "server" flow and the "implicit" flow. The server flow allows the back-end server of an application to verify the identity of the person using a browser or mobile device. The implicit flow is used when a client-side application (typically a JavaScript app running in the browser) needs to access APIs directly instead of via its back-end server.

This document describes how to perform the server flow for authenticating the user. The implicit flow is significantly more complicated because of security risks in handling and using tokens on the client side. If you need to implement an implicit flow, we highly recommend using Google Sign-In.

Server flow

Make sure you set up your app in the Developers Console to enable it to use these protocols and authenticate your users. When a user tries to log in with Google, you need to:

  1. Create an anti-forgery state token
  2. Send an authentication request to Google
  3. Confirm the anti-forgery state token
  4. Exchange code for access token and ID token
  5. Obtain user information from the ID token
  6. Authenticate the user

1. Create an anti-forgery state token

You must protect the security of your users by preventing request forgery attacks. The first step is creating a unique session token that holds state between your app and the user's client. You later match this unique session token with the authentication response returned by the Google OAuth Login service to verify that the user is making the request and not a malicious attacker. These tokens are often referred to as cross-site request forgery (CSRF) tokens.

One good choice for a state token is a string of 30 or so characters constructed using a high-quality random-number generator. Another is a hash generated by signing some of your session state variables with a key that is kept secret on your back-end.

The following code demonstrates generating unique session tokens.


You must download the Google APIs client library for PHP to use this sample.
  // Create a state token to prevent request forgery.
  // Store it in the session for later validation.
  $state = sha1(openssl_random_pseudo_bytes(1024));
  $app['session']->set('state', $state);
  // Set the client ID, token state, and application name in the HTML while
  // serving it.
  return $app['twig']->render('index.html', array(
      'STATE' => $state,


You must download the Google APIs client library for Java to use this sample.
  // Create a state token to prevent request forgery.
  // Store it in the session for later validation.
  String state = new BigInteger(130, new SecureRandom()).toString(32);
  request.session().attribute("state", state);
  // Read index.html into memory, and set the client ID,
  // token state, and application name in the HTML before serving it.
  return new Scanner(new File("index.html"), "UTF-8")
      .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
      .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)


You must download the Google APIs client library for Python to use this sample.
  # Create a state token to prevent request forgery.
  # Store it in the session for later validation.
  state = hashlib.sha256(os.urandom(1024)).hexdigest()
  session['state'] = state
  # Set the client ID, token state, and application name in the HTML while
  # serving it.
  response = make_response(

2. Send an authentication request to Google

The next step is forming an HTTPS GET request with the appropriate URI parameters. Note the use of HTTPS rather than HTTP in all the steps of this process; HTTP connections are refused. You should retrieve the base URI from the Discovery document using the key authorization_endpoint. The following discussion assumes the base URI is https://accounts.google.com/o/oauth2/auth.

For a basic request, specify the following parameters:

  • client_id, which you obtain from the Developers Console.
  • response_type, which in a basic request should be code. (Read more at response_type.)
  • scope, which in a basic request should be openid email. (Read more at scope.)
  • redirect_uri should be the HTTP endpoint on your server that will receive the response from Google. You specify this URI in the Developers Console.
  • state should include the value of the anti-forgery unique session token, as well as any other information needed to recover the context when the user returns to your application, e.g., the starting URL. (Read more at state.)
  • login_hint can be the user's email address or the sub string, which is equivalent to the user's Google ID. If you do not provide a login_hint and the user is currently logged in, the consent screen includes a request for approval to release the user’s email address to your app. (Read more at login_hint.)
  • Use the openid.realm if you are migrating an existing application from OpenID 2.0 to OpenID Connect. For details, see Migrating off of OpenID 2.0.
  • Use the hd parameter to limit sign-in to a particular Google Apps hosted domain. (Read more at hd.)

Here is an example of a complete OpenID Connect authentication URI, with line breaks and spaces for readability:


Users are required to give consent if your app requests any new information about them, or if your app requests account access that they have not previously approved.

3. Confirm anti-forgery state token

The response is sent to the redirect_uri that you specified in the request. All responses are returned in the query string, as shown below:


On the server, you must confirm that the state received from Google matches the session token you created in Step 1. This round-trip verification helps to ensure that the user, not a malicious script, is making the request.

The following code demonstrates confirming the session tokens that you created in Step 1:


You must download the Google APIs client library for PHP to use this sample.
  // Ensure that there is no request forgery going on, and that the user
  // sending us this connect request is the user that was supposed to.
  if ($request->get('state') != ($app['session']->get('state'))) {
    return new Response('Invalid state parameter', 401);


You must download the Google APIs client library for Java to use this sample.
  // Ensure that there is no request forgery going on, and that the user
  // sending us this connect request is the user that was supposed to.
  if (!request.queryParams("state").equals(
      request.session().attribute("state"))) {
    return GSON.toJson("Invalid state parameter.");


You must download the Google APIs client library for Python to use this sample.
  # Ensure that the request is not a forgery and that the user sending
  # this connect request is the expected user.
  if request.args.get('state', '') != session['state']:
    response = make_response(json.dumps('Invalid state parameter.'), 401)
    response.headers['Content-Type'] = 'application/json'
    return response

4. Exchange code for access token and ID token

The response includes a code parameter, a one-time authorization code that your server can exchange for an access token and ID token. Your server makes this exchange by sending an HTTPS POST request. The POST request is sent to the token endpoint, which you should retrieve from the Discovery document using the key token_endpoint. The following discussion assumes the endpoint is https://www.googleapis.com/oauth2/v3/token. The request must include the following parameters in the POST body:

Field Description
code The authorization code that is returned from the initial request.
client_id The client ID that you obtain from the Developers Console, as described in Obtain OAuth 2.0 credentials.
client_secret The client secret that you obtain from the Developers Console, as described in Obtain OAuth 2.0 credentials.
redirect_uri The URI that you specify in the Developers Console, as described in Set a redirect URI.
grant_type This field must contain a value of authorization_code, as defined in the OAuth 2.0 specification.

The actual request might look like the following example:

POST /oauth2/v3/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded


A successful response to this request contains the following fields in a JSON array:

Field Description
access_token A token that can be sent to a Google API.
id_token A JWT that contains identity information about the user that is digitally signed by Google.
expires_in The remaining lifetime of the access token.
token_type Identifies the type of token returned. At this time, this field always has the value Bearer.
refresh_token (optional) This field is only present if access_type=offline is included in the authentication request. For details, see Refresh tokens.

5. Obtain user information from the ID token

An ID Token is a JWT (JSON Web Token), that is, a cryptographically signed Base64-encoded JSON object. Normally, it is critical that you validate an ID token before you use it, but since you are communicating directly with Google over an intermediary-free HTTPS channel and using your client secret to authenticate yourself to Google, you can be confident that the token you receive really comes from Google and is valid. If your server passes the ID token to other components of your app, it is extremely important that the other components validate the token before using it.

Since most API libraries combine the validation with the work of decoding the base64 and parsing the JSON, you will probably end up validating the token anyway as you access the fields in the ID token.

An ID token's payload

An ID token is a JSON object containing a set of name/value pairs. Here’s an example, formatted for readability:

 "hd":"example.com" }

Google ID Tokens may contain the following fields (known as claims):

Claim Provided Description
iss always The Issuer Identifier for the Issuer of the response. Always accounts.google.com or https://accounts.google.com for Google ID tokens.
at_hash Access token hash. Provides validation that the access token is tied to the identity token. If the ID token is issued with an access token in the server flow, this is always included. This can be used as an alternate mechanism to protect against cross-site request forgery attacks, but if you follow Step 1 and Step 3 it is not necessary to verify the access token.
email_verified True if the user's e-mail address has been verified; otherwise false.
sub always An identifier for the user, unique among all Google accounts and never reused. A Google account can have multiple emails at different points in time, but the sub value is never changed. Use sub within your application as the unique-identifier key for the user.
azp The client_id of the authorized presenter. This claim is only needed when the party requesting the ID token is not the same as the audience of the ID token. This may be the case at Google for hybrid apps where a web application and Android app have a different client_id but share the same project.
email The user’s email address. This may not be unique and is not suitable for use as a primary key. Provided only if your scope included the string "email".
aud always Identifies the audience that this ID token is intended for. It must be one of the OAuth 2.0 client IDs of your application.
iat always The time the ID token was issued, represented in Unix time (integer seconds).
exp always The time the ID token expires, represented in Unix time (integer seconds).
hd The hosted Google Apps domain of the user. Provided only if the user belongs to a hosted domain.

6. Authenticate the user

After obtaining user information from the ID token, you should query your app's user database. If the user already exists in your database, you should start an application session for that user.

If the user does not exist in your user database, you should redirect the user to your new-user sign-up flow. You may be able to auto-register the user based on the information you receive from Google, or at the very least you may be able to pre-populate many of the fields that you require on your registration form. In addition to the information in the ID token, you can get additional user profile information at our user profile endpoints.

Advanced topics

The following sections describe the Google OAuth 2.0 API in greater detail. This information is intended for developers with advanced requirements around authentication and authorization.

Access to other Google APIs

One of the advantages of using OAuth 2.0 for authentication is that your application can get permission to use other Google APIs (such as YouTube, Google Drive, Calendar, or Contacts) at the same time as you authenticate the user. To do this, include the other scopes that you need in the authentication request that you send to Google. For example, to add Google Drive access to your authentication request, pass a scope parameter of openid email https://www.googleapis.com/auth/drive. The user is prompted appropriately on the consent screen. The access token that you receive back from Google allows you to access all the APIs related to the scopes you requested.

Refresh tokens

In your request for API access you can request a refresh token to be returned during the code exchange. A refresh token provides your app continuous access to Google APIs while the user is not logged into your application. To request a refresh token, add access_type=offline to the authentication request.


  • Be sure to store the refresh token safely and permanently, because you can only obtain a refresh token the first time that you perform the code exchange flow.
  • There are limits on the number of refresh token that are issued—one limit per client/user combination, and another per user across all clients. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens stop working.

For more information, see Offline Access and Using a refresh token.

You can prompt the user to re-authorize your app by adding the prompt=consent parameter to the authentication request. When prompt=consent is included, the consent screen is displayed every time the user logs into your app. For this reason, include prompt=consent only when necessary.

For more about the prompt parameter, see prompt in the URI parameter table.

Authentication URI parameters

The following table gives more complete descriptions of the parameters accepted by Google's OAuth 2.0 authentication API.

Parameter Required Description
client_id (Required) The client ID string that you obtain from the Developers Console, as described in Obtain OAuth 2.0 credentials.
response_type (Required) If the value is code, launches a Basic flow, requiring a POST to the token endpoint to obtain the tokens. If the value is token id_token or id_token token, launches an Implicit flow, requiring the use of Javascript at the redirect URI to retrieve tokens from the URI #fragment.
scope (Required)

The scope value must begin with the string openid and then include profile or email or both.

If email is present, the ID token includes email and email_verified claims.

In addition to these OpenID-specific scopes, your scope argument can also include other scope strings. All scope strings must be space-separated. For example, if you wanted per-file access to a user’s Google Drive, your scope might be openid profile email https://www.googleapis.com/auth/drive.file.

For information about available login scopes, see Login scopes. To see the available scopes for all Google APIs, visit the APIs Explorer.

redirect_uri (Required) Determines where the response is sent. The value of this parameter must exactly match one of the values that you set in the Google Developers Console (including the HTTP or HTTPS scheme, case, and trailing '/', if any).
state (Optional, but strongly recommended)

An opaque string that is round-tripped in the protocol; that is to say, it is returned as a URI parameter in the Basic flow, and in the URI #fragment in the Implicit flow.

The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request. If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This provides protection against attacks such as cross-site request forgery.

prompt (Optional) A space-delimited list of string values that specifies whether the authorization server prompts the user for reauthentication and consent. The possible values are:
  • none
    The authorization server does not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not pre-configured consent for the requested scopes. You can use none to check for existing authentication and/or consent.
  • consent
    The authorization server prompts the user for consent before returning information to the client.
  • select_account
    The authorization server prompts the user to select a user account. This allows a user who has multiple accounts at the authorization server to select amongst the multiple accounts that they may have current sessions for.
If no value is specified and the user has not previously authorized access, then the user is shown a consent screen.
display (Optional) An ASCII string value for specifying how the authorization server displays the authentication and consent user interface pages. The following values are specified, and accepted by the Google servers, but do not have any effect on its behavior: page, popup, touch, and wap.
login_hint (Optional) When your app knows which user it is trying to authenticate, it can provide this parameter as a hint to the authentication server. Passing this hint suppresses the account chooser and either pre-fill the email box on the sign-in form, or select the proper session (if the user is using multiple sign-in), which can help you avoid problems that occur if your app logs in the wrong user account. The value can be either an email address or the sub string, which is equivalent to the user's Google ID.
access_type (Optional) The allowed values are offline and online. The effect is documented in Offline Access; if an access token is being requested, the client does not receive a refresh token unless offline is specified.
include_granted_scopes true or false If this is provided with the value true, and the authorization request is granted, the authorization will include any previous authorizations granted to this user/application combination for other scopes; see Incremental Authorization.

Note that you cannot do incremental authorization with the Installed App flow.

openid.realm (Optional) openid.realm is a parameter from the OpenID 2.0 protocol, not from OAuth 2.0. It is used in OpenID 2.0 requests to signify the URL-space for which an authentication request is valid. Use openid.realm if you are migrating an existing application from OpenID 2.0 to OpenID Connect. For more details, see Migrating off of OpenID 2.0.
hd (Optional)

The hd (hosted domain) parameter streamlines the login process for Google Apps hosted accounts. By including the domain of the user (for example, mycollege.edu), you restrict sign-in to accounts at that domain. For Google Apps customers that have SAML set up with their own authentication infrastructure, the hd parameter automatically redirects to that user's SAML resource to log in.

To protect against client-side request modification, be sure to validate that the returned ID token has a matching hd claim (which is proof the account does belong to the hosted domain).

Validating an ID token

You need to validate all ID tokens on your server unless you know that they came directly from Google. For example, your server must verify as authentic any ID tokens it receives from your client apps.

The following are common situations where you might send ID tokens to your server:

  • Sending ID tokens with requests that need to be authenticated. The ID tokens tell you the particular user making the request and for which client that ID token was granted.
  • Sending ID tokens that contain OpenID 2.0 identifiers (openid_id) that need to be mapped to the Google ID (sub).

ID tokens are sensitive and can be misused if intercepted. You must ensure that these tokens are handled securely by transmitting them only over HTTPS and only via POST data or within request headers. If you store them on your server, you must also store them securely.

One thing that makes ID tokens useful is that fact that you can pass them around different components of your app. These components can use an ID token as a lightweight authentication mechanism authenticating the app and the user. But before you can use the information in the ID token or rely on it as an assertion that the user has authenticated, you must validate it.

Validation of an ID token requires several steps:

  1. Verify that the ID token is a JWT which is properly signed with an appropriate Google public key.
  2. Verify that the value of aud in the ID token is equal to your app’s client ID.
  3. Verify that the value of iss in the ID token is equal to accounts.google.com or https://accounts.google.com.
  4. Verify that the expiry time (exp) of the ID token has not passed.
  5. If you passed a hd parameter in the request, verify that the ID token has a hd claim that matches your Google Apps hosted domain.

Steps 2 to 5 involve only string and date comparisons which are quite straight forward, so we won't detail them here.

The first step is more complex, and involves cryptographic signature checking. For debugging purposes, you can use Google’s tokeninfo endpoint. Suppose your ID token’s value is XYZ123. Then you would dereference the URI https://www.googleapis.com/oauth2/v1/tokeninfo?id_token=XYZ123. If the token is valid, the response would be its decoded JSON form.

This involves an HTTP round trip, introducing latency and the potential for network breakage. The tokeninfo endpoint is useful for debugging but for production purposes, we recommend that you retrieve Google’s public keys from the keys endpoint and perform the validation locally. You should retrieve the keys URI from the Discovery document using the key jwks_uri.

Since Google changes its public keys only infrequently (on the order of once per day), you can cache them and, in the vast majority of cases, perform local validation much more efficiently than by using the tokeninfo endpoint. This requires retrieving and parsing certificates, and making the appropriate crypto calls to check the signature. Fortunately, there are well-debugged libraries available in a wide variety of languages to accomplish this.

Sample validation code for ID tokens

Samples that demonstrate how to perform ID token validation are available in the following languages. As an example, the Java sample code uses the open-source GoogleIDToken and GoogleIDTokenVerifier classes. These libraries normally validate the token and return its parsed payload (if valid) in one step.

Obtaining user profile information

To obtain additional profile information about the user, you can use the access token (which your application receives during the authentication flow) with two different endpoints. Unless you are using the plus.login scope, these endpoints provide identical information, just formatted differently.

Google Sign-In

If you are using Google Sign-In, retrieve user profile information from the people.get endpoint. To do this, add your access token to the authorization header and make an HTTPS GET request to the following URI:


Use your access token to authenticate the request, as described in people.get. Note that the response does not use the OpenID Connect format.

OpenID Connect

If you want to use the OpenID Connect standard and need attributes formatted accordingly:

  1. To be OpenID-compliant, you must include the openid profile scope in your authentication request.

    If you want the user’s email address to be included, you can optionally request the openid email scope. To specify both profile and email, you can include the following parameter in your authentication request URI:

  2. Add your access token to the authorization header and make an HTTPS GET request to the userinfo endpoint, which you should retrieve from the Discovery document using the key userinfo_endpoint. The response includes information about the user, as described in people.getOpenIdConnect. Users may choose to supply or withhold certain fields, so you might not get information for every field to which your scopes request access.

The Discovery document

The OpenID Connect protocol requires the use of multiple endpoints for authenticating users, and for requesting resources including tokens, user information, and public keys.

To simplify implementations and increase flexibility, OpenID Connect allows the use of a "Discovery document," a JSON document found at a well-known location containing key-value pairs which provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, userinfo, and public-keys endpoints. The Discovery document for Google's OpenID Connect service may be retrieved from:


Here is an example of such a document; the field names are those specified in OpenID Connect Discovery 1.0 (refer to that document for their meanings). The values are purely illustrative and might change, although they are copied from from a recent version of the actual Google Discovery document:

 "issuer": "https://accounts.google.com",
 "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
 "token_endpoint": "https://www.googleapis.com/oauth2/v4/token",
 "userinfo_endpoint": "https://www.googleapis.com/oauth2/v3/userinfo",
 "revocation_endpoint": "https://accounts.google.com/o/oauth2/revoke",
 "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
 "response_types_supported": [
  "code token",
  "code id_token",
  "token id_token",
  "code token id_token",
 "subject_types_supported": [
 "id_token_signing_alg_values_supported": [
 "scopes_supported": [
 "token_endpoint_auth_methods_supported": [
 "claims_supported": [

To use Google's OpenID Connect services, you should hard-code the Discovery-document URI (https://accounts.google.com/.well-known/openid-configuration) into your application. Your application fetches the document, then retrieves endpoint URIs from it as needed. For example, to authenticate a user, your code would retrieve the value of the authorization_endpoint key and use its value (https://accounts.google.com/o/oauth2/auth in the example above) as the base URI for authentication requests that are sent to Google.

You may be able to avoid an HTTP round-trip by caching the values from the Discovery document. Standard HTTP caching headers are used and should be respected.

Client libraries

The following client libraries make implementing OAuth 2.0 simpler by integrating with popular frameworks:

OpenID Connect compliance

Google's OAuth 2.0 authentication system supports the required features of the OpenID Connect Core specification. Any client which is designed to work with OpenID Connect should interoperate with this service (with the exception of the OpenID Request Object).