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 byusing a client library, you canset up Application Default Credentials, and the client libraryhandles tokens for you. This is the recommended approach.
What tokens are
For authentication and authorization, a token is a digital object that containsinformation about the identity of the principal making the request and what kindof access they are authorized for. In most authentication flows, theapplication—or a library used by the application—exchanges acredential for a token, which determines which resources the application isauthorized to access.
Types of tokens
Different types of tokens are used in different environments. The followingtoken types are described on this page:
- Access tokens
- ID tokens
- Self-signed JWTs
- Refresh tokens
- Federated tokens
- Bearer tokens
This page does not discuss API keys or Client IDs,which are considered credentials.
Access tokens
Access tokens are opaque tokens that conform to theOAuth 2.0 framework. They contain authorizationinformation, but not identity information. They are used to authenticate andprovide authorization information to Google APIs.
If you use Application Default Credentials (ADC) and theCloud Client Libraries or Google API Client Libraries, you do not needto 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 proprietaryformat; applications cannot inspect them. You can get the information from avalid (not expired or revoked) access token by using the Google OAuth 2.0tokeninfo 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": "[email protected]", "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 hasexpired, your token management code must get a new one.
If you need an access token with a longer or shorter lifetime, you can use theserviceAccounts.generateAccessToken methodto create the token. This method enables you to choose the lifetime of thetoken, with a maximum lifetime of 12 hours.
If you want to extend the token lifetime beyond the default, you must create anorganization policy that enables the iam.allowServiceAccountCredentialLifetimeExtensionconstraint. You can't create access tokens with an extendedlifetime for user credentials or external identities. For more information, seeCreate a short-lived access token.
ID tokens
ID tokens are JSON Web Tokens (JWTs) that conform tothe OpenID Connect (OIDC) specification. They arecomposed of a set of key-value pairs called claims.
Unlike access tokens, which are opaque objects that cannot be inspected by theapplication, 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 forwhom the ID token was issued, is available for use by the application.
For more information about Google’s OIDC implementation, seeOpenID Connect. For best practices for working with JWTs, seeJSON Web Token Best Current Practices.
ID token contents
You can inspect a valid (not expired or revoked) ID token by using the GoogleOAuth 2.0 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": "[email protected]", "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 bea replay intended for another system.
Generally, when you get an ID token, you use the credentialsprovided by a service account, rather than user credentials. This is because theaud claim for ID tokens generated using user credentials is statically boundto the application the user used to authenticate. When you use a service accountto 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 asCloud Run, Cloud Functions, or Identity-Aware Proxy, Google validates IDtokens 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, seeValidating an ID token.
Self-signed JSON Web Tokens (JWTs)
Self-signed JWTs are required toauthenticate to APIs deployed with API Gateway. Inaddition, you can use self-signed JWTs to authenticate to some Google APIswithout having to get an access token from the Authorization Server.
Creating self-signed JWTs is recommended if you are creating your own clientlibraries to access Google APIs, but is an advanced workflow. For moreinformation about self-signed JWTs, seeCreating a self-signed JSON Web Token.For best practices for working with JWTs, seeJSON Web Token Best Current Practices.
Refresh tokens
By default, access tokens and ID tokens are valid for1 hour. A refresh token is a special token that is usedto obtain additional access tokens or ID tokens. When your application firstauthenticates, it receives an access token or ID token, as well as a refreshtoken. Later, if the application needs to access resources again, and thepreviously provided token has expired, it uses the refresh token to request anew token. Refresh tokens are used only for user authentication,such as for Cloud Identity or Google Workspace.
Refresh tokens don't have a set lifetime; they can expire, butotherwise they continue to be usable. For user access in Google Workspace orCloud Identity premium edition, you canconfigure the session length to ensure that a user must login periodically to retain access to Google Cloud services.
If your application is creating and managing its own tokens, it also needs tomanage refresh tokens. For more information, see the following links:
- OAuth 2.0 for Server to Server Applications
- OAuth 2.0 for Web Server Applications.
- OAuth 2.0 for Client-side Web Applications
- OAuth 2.0 for TV and Limited-Input Device Applications
Federated tokens
Federated tokens are used as an intermediate step byworkload identity federation. Federated tokens are returned by theSecurity Token Service and cannot be used directly. They must beexchanged for an access token using service accountimpersonation.
Bearer tokens
Bearer tokens are a general class of token that grants access to theparty in possession of the token. Access tokens, ID tokens, and self-signed JWTsare all bearer tokens.
Using bearer tokens for authentication relies on the security provided byan encrypted protocol, such as HTTPS; if a bearer token is intercepted, it canbe used by a bad actor to gain access.
If bearer tokens don’t provide sufficient security for your use case, consideradding another layer of encryption or using a mutual Transport Layer Security(mTLS) solution such as BeyondCorp Enterprise, which limits access to onlyauthenticated users on a trusted device.
What's next
- Learn how to set up credentials for ADC.
- See information aboutgetting ID tokens.
- Review authentication use cases.
- Understand more about authentication at Google.
I'm an expert in authentication and authorization mechanisms, particularly regarding token-based security models within the context of Google APIs and Google Cloud services. My expertise stems from years of practical experience in designing, implementing, and troubleshooting authentication systems across various environments.
Authentication tokens are digital objects crucial for validating the identity of an entity making a request and specifying the level of access it possesses. In the realm of Google APIs and services, several types of tokens are utilized, each serving distinct purposes:
-
Access tokens: These opaque tokens conform to the OAuth 2.0 framework, containing authorization but not identity information. They are used to authenticate and provide authorization details to Google APIs.
-
ID tokens: JSON Web Tokens (JWTs) adhering to the OpenID Connect (OIDC) specification. Unlike access tokens, ID tokens are meant to be inspected and utilized by applications, providing information about the issuer, audience, subject, and expiration time.
-
Self-signed JWTs: These are essential for authenticating to APIs deployed with API Gateway and certain Google APIs without requiring an access token from the Authorization Server. They're recommended for creating custom client libraries accessing Google APIs.
-
Refresh tokens: Special tokens used to obtain additional access or ID tokens when the initially provided tokens expire. They are specifically employed for user authentication, such as Cloud Identity or Google Workspace.
-
Federated tokens: Intermediary tokens in workload identity federation, obtained from the Security Token Service. They require exchange for an access token using service account impersonation.
-
Bearer tokens: A broad category encompassing access tokens, ID tokens, and self-signed JWTs. These tokens grant access to the possessor, and their security relies on encrypted protocols like HTTPS.
These tokens serve different purposes and have varying lifetimes. Access tokens and ID tokens typically last for one hour, while refresh tokens persist until their expiration or revocation.
Understanding and managing these tokens are crucial for secure access to Google APIs and services. Utilizing appropriate token types and their associated endpoints (like tokeninfo) helps in validating, inspecting, and managing these tokens effectively for robust authentication and authorization practices.
