This page discusses the types of tokens used for authentication to Google APIs, Google Cloud services, and customer-created services hosted on Google Cloud.
If you are accessing Google APIs and services by using a client library, you can set up Application Default Credentials, and the client library handles tokens for you. This is the recommended approach.
What tokens are
For authentication and authorization, a token is a digital object that contains information about the identity of the principal making the request and what kind of access they are authorized for. In most authentication flows, the application—or a library used by the application—exchanges a credential for a token, which determines which resources the application is authorized to access.
Types of tokens
Different types of tokens are used in different environments. The following token types are described on this page:
This page does not discuss API keys or Client IDs, which are considered credentials.Access tokens
Access tokens are opaque tokens that conform to the OAuth 2.0 framework. They contain authorization information, but not identity information. They are used to authenticate and provide authorization information to Google APIs.
If you use Application Default Credentials (ADC) and the Cloud Client Libraries or Google API Client Libraries, you do not need to manage access tokens; the libraries automatically retrieve the credential, exchange it for an access token, and refresh the access token as needed.
Access token contents
Access tokens are opaque tokens, which means that they are in a proprietary format; applications cannot inspect them.
You can get the information from a
valid (not expired or revoked) access token by using the Google OAuth 2.0
tokeninfo endpoint.
Replace ACCESS_TOKEN with the valid, unexpired access token.
curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"
This command returns something similar to the following example:
{
"azp": "32553540559.apps.googleusercontent.com",
"aud": "32553540559.apps.googleusercontent.com",
"sub": "111260650121245072906",
"scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
"exp": "1650056632",
"expires_in": "3488",
"email": "user@example.com",
"email_verified": "true"
}
The following table lists the most important fields to understand:
| Field | Description |
|---|---|
azp |
The project, email, or service account ID of the application that
requested the token. This value is included only if
https://www.googleapis.com/auth/userinfo.email is
specified in the list of scopes.
|
scope |
The OAuth scopes that have been added to this access token. For
Google Cloud services, it is a best practice to use the
https://www.googleapis.com/auth/cloud-platform
scope, which includes all Google Cloud APIs, together with
Identity and Access Management (IAM),
which provides fine-grained access control.
|
expires_in |
The number of seconds until the token expires. For more information, see Access token lifetime. |
Access token lifetime
By default, access tokens are good for 1 hour (3,600 seconds). When the access token has expired, your token management code must get a new one.
If you need an access token with a longer or shorter lifetime, you can use the
serviceAccounts.generateAccessToken method
to create the token. This method enables you to choose the lifetime of the
token, with a maximum lifetime of 12 hours.
If you want to extend the token lifetime beyond the default, you must create an
organization policy that enables the
iam.allowServiceAccountCredentialLifetimeExtension constraint.
For more information, see
Create a short-lived access token.
ID tokens
ID tokens are JSON Web Tokens (JWTs) that conform to the OpenID Connect (OIDC) specification. They are composed of a set of key-value pairs called claims.
Unlike access tokens, which are opaque objects that cannot be inspected by the application, ID tokens are meant to be inspected and used by the application. Information from the token, such as Who signed the token or the identity for whom the ID token was issued, is available for use by the application.
For more information about Google's implementation of OIDC, see OpenID Connect. For best practices for working with JWTs, see JSON Web Token Best Current Practices.ID token contents
You can inspect a valid (not expired or revoked) ID token by using the
tokeninfo endpoint.
Replace ID_TOKEN with the valid, unexpired ID token.
curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"
This command returns something similar to the following example:
{
"iss": "https://accounts.google.com",
"azp": "32555350559.apps.googleusercontent.com",
"aud": "32555350559.apps.googleusercontent.com",
"sub": "111260650121185072906",
"hd": "google.com",
"email": "user@example.com",
"email_verified": "true",
"at_hash": "_LLKKivfvfme9eoQ3WcMIg",
"iat": "1650053185",
"exp": "1650056785",
"alg": "RS256",
"kid": "f1338ca26835863f671403941738a7b49e740fc0",
"typ": "JWT"
}
The following table describes required or commonly used ID token claims:
| Claim | Description |
|---|---|
iss |
The issuer, or signer, of the token. For Google-signed ID tokens, this
value is https://accounts.google.com.
|
azp |
Optional. Who the token was issued to. |
aud |
The audience of the token. The value of this claim must match the
application or service that uses the token to authenticate the request.
For more information, see
ID token aud claim.
|
sub |
The subject: the ID that represents the principal making the request. |
iat |
Unix epoch time when the token was issued. |
exp |
Unix epoch time when the token expires. |
Other claims might be present, depending on the issuer and the application.
ID token aud claim
The aud claim describes the service name this token was created to invoke.
If a service receives an ID token, it must verify its integrity (signature),
validity (is it expired) and if the aud claim matches the name it expects.
If it does not match, the service should reject the token, because it could be
a replay intended for another system.
Generally, when you get an ID token, you use the credentials
provided by a service account, rather than user credentials. This is because the
aud claim for ID tokens generated using user credentials is statically bound
to the application the user used to authenticate. When you use a service account
to acquire an ID token, you can specify a different value for the aud claim.
ID token lifetime
ID tokens are valid for up to 1 hour (3,600 seconds). When an ID token expires, you must acquire a new one.
ID token validation
When your service or application uses a Google service such as Cloud Run, Cloud Run functions, or Identity-Aware Proxy, Google validates ID tokens for you; in these cases, the ID tokens must be signed by Google.
If you need to validate ID tokens within your application, you can do so, although this is an advanced workflow. For information, see Validating an ID token.
Self-signed JSON Web Tokens (JWTs)
You can use self-signed JWTs to authenticate to some Google APIs without having to get an access token from the Authorization Server.Creating self-signed JWTs is recommended if you are creating your own client libraries to access Google APIs, but is an advanced workflow. For more information about self-signed JWTs, see Creating a self-signed JSON Web Token. For best practices for working with JWTs, see JSON Web Token Best Current Practices.
Refresh tokens
Your IdP manages the lifetime of long-lived tokens. An exception is local ADC files, which contain refresh tokens used by the authentication libraries to refresh access tokens automatically for client libraries.
Federated tokens
Federated tokens are generated from federated identities by Workload Identity Federation and Workforce Identity Federation.
Federated tokens are used in the following ways:
For services that support these tokens, federated tokens can be used directly. This method is sometimes called direct access.
Federated tokens can be exchanged for an OAuth 2.0 access token, by using the Security Token Service API.
The federated tokens returned by Workload Identity Federation and Workforce Identity Federation are not equivalent to the tokens returned by Workload Identity Federation for GKE. For more information about how Google Kubernetes Engine applications authenticate to Google APIs, see Configure applications to use Workload Identity Federation for GKE.
Bearer tokens
Bearer tokens are a general class of token that grants access to the party in possession of the token. Access tokens, ID tokens, and self-signed JWTs are all bearer tokens.
Using bearer tokens for authentication relies on the security provided by
an encrypted protocol, such as HTTPS; if a bearer token is intercepted, it can
be used by a bad actor to gain access.
What's next
- Learn how to set up credentials for ADC.
- See information about getting ID tokens.
- Understand more about authentication methods.