Google Cloud issues multiple types of tokens, which differ by their purpose andthe parties they're exchanged between.

The following table gives an overview of the main token categories, within whichare different token types.

Access and identity tokens arebearer tokens. Bearer tokens are a generalclass of token that grant access to the party in possession of the token.

Using bearer tokens for authentication relies on the security provided by anencrypted protocol, such as HTTPS. If a bearer token is intercepted, it can beused by a bad actor to gain access.

If bearer tokens don't provide sufficient security for your use case, you candecrease the risk of token theft by usingcontext-aware access, limitingthe lifetime of access tokens, or by using a mutual Transport Layer Security(mTLS) solution such asChrome Enterprise Premium.

Access tokens

Access tokens allow clients to make authenticated calls to Google Cloud APIs.Google Cloud supports multiple different types of access tokens, which have thefollowing properties in common:

• They authenticate a principal, which can be a user or a workload.

• They're issued to one particular client.

• They're short-lived and expire after at most a few hours.

• They're restricted to certain OAuth scopes, endpoints, or resources. Thismeans that an access token typically doesn't grant access to all of a user'sresources, but only to a certain subset of them.

Access tokens can differ in the following ways:

• Issuer: The party that issues the token.

• Principal: The type of principal that the token can authenticate.

• Restrictions: The restrictions that can be imposed on the token.

The following table lists the different types of access tokens:

The different types of access tokens also exhibit different security properties:

• Format: Some access tokens are opaque, meaning they are in a proprietaryformat and can't be inspected. Other tokens are encoded as a JSON Web Token,which can be decoded by the client.
• Introspectability: Some opaque tokens can be introspected using theGoogle Cloud API, whereas others can't.

• Lifetime: Tokens differ in lifetime and to what extent they can bemodified.

• Revocability: Some tokens can be revoked. Other tokens remain valid untilexpiry.

The following table summarizes the differences between the access token types.

User access tokens

User access tokens authenticate a user and authorize a client to act on theuser's behalf:

The authenticated principal is either amanaged user accountor aconsumer account.The client can be a web application or a native application.

User access tokens are opaque. For diagnostic purposes, you can introspect anaccess token by using the following command, replacingACCESS_TOKEN with a valid access token:

curl"https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

This command produces output similar to the following example:

{"azp":"0000000000.apps.googleusercontent.com","aud":"0000000000.apps.googleusercontent.com","sub":"00000000000000000000","scope":"openid https://www.googleapis.com/auth/userinfo.email","exp":"1744687132","expires_in":"3568","email":"user@example.com","email_verified":"true"}

The output includes the following fields:

User access tokens automatically expire after one hour, but can berevokedearlier if needed.

By default, user access tokens are bearer tokens, which means they're not boundto any particular communication channel, network, or additional credential.You can optionally implement token binding bydeploying certificate-based accessso that user access tokens can only be used in conjunction with a valid mTLSclient certificate.

Service account access tokens

Service account access tokens authenticate a service account. The tokens areopaqueand you can introspect them using thehttps://oauth2.googleapis.com/tokeninfoAPI.

For a service account access token, the API returns output similar to thefollowing example:

{"azp":"000000000000000000000","aud":"000000000000000000000","scope":"https://www.googleapis.com/auth/userinfo.email","exp":"1744687132","expires_in":"3568","email":"service-account@example.iam.gserviceaccount.com","email_verified":"true","access_type":"online"}

A service account token includes the following fields:

Service account access tokens can't be revoked and stay valid until they expire.

By default, service account access tokens expire after one hour. By using theserviceAccounts.generateAccessTokenmethod, you can request tokens with different lifetimes. Because longer tokenlifetimes can increase risk, you must configure theiam.allowServiceAccountCredentialLifetimeExtensionconstraint to allow clients to request service account access tokens withlifetimes longer than one hour.

Domain-wide delegation tokens

Domain-wide delegation tokens authenticate a user and authorize a serviceaccount to act on the user's behalf. The tokens are opaque and you canintrospect them using thehttps://oauth2.googleapis.com/tokeninfoAPI.

For a domain-wide delegation token, the API returns output similar to thefollowing example:

{"azp":"000000000000000000000","aud":"000000000000000000000","scope":"https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/userinfo.email","exp":"1744688957","expires_in":"3540","email":"user@example.com","email_verified":"true","access_type":"offline"}

A domain-wide delegation token includes the following fields:

Domain-wide delegation tokens automatically expire after one hour, and theycan't be revoked.

Service account JSON Web Tokens

Service account JSON Web Tokens (JWTs) authenticate a service account. Whereasservice account access tokens are issued by anauthorization server, service account JWTs can be issued by the client itself.

Sometimes these are called "self-signed" JWTs. They can be useful when you needto authenticate to some Google APIs without getting an access token from theauthorization server—for example, when creating your own client libraries.

To issue a service account JWT, clients must perform the following steps:

1. Prepare a JSON web signature payload that includes the service account'semail address, an OAuth scope or API endpoint, and an expiry time.

2. Sign the payload using a service account key of the respective serviceaccount. Clients can sign the payload offline by using a user-managedservice account key, or online by using thesignJwt method and aGoogle-managed service account key. For more information, seeCreate a self-signed JSON Web Token

A decoded service account JWT looks similar to the following, withSIGNATURE replaced by the token's signature:

{"alg":"RS256","kid":"290b7bf588eee0c35d02bf1164f4336229373300","typ":"JWT"}.{"iss":"service-account@example.iam.gserviceaccount.com","sub":"service-account@example.iam.gserviceaccount.com","scope":"https://www.googleapis.com/auth/cloud-platform","exp":1744851267,"iat":1744850967}.SIGNATURE

Instead of specifying an OAuth scope in thescope key, a service account JWTcan specify an API endpoint in theaud key:

{"alg":"RS256","kid":"290b7bf588eee0c35d02bf1164f4336229373300","typ":"JWT"}.{"iss":"service-account@example.iam.gserviceaccount.com","sub":"service-account@example.iam.gserviceaccount.com","aud":"https://cloudresourcemanager.googleapis.com/","exp":1744854799,"iat":1744851199}.SIGNATURE

A service account JWT includes the following fields:

Service account JWTs can be valid for up to one hour, and they can't be revoked.

Federated access tokens

Federated access tokens authenticate a identity workforce pool principal or aworkload identity pool principal.

Workforce Identity Federation lets clients exchange an external token against afederated access token that authenticates a workforce pool principal. Theworkforce identity pool principal is identified by a principal identifier similarto the following:

principal://iam.googleapis.com/locations/global/workforcePools/POOL/subject/raha@altostrat.com.

Workload Identity Federation lets clients exchange an external token against afederated access token that authenticates a workload pool principal. Theworkload identity pool principal is identified by a principal identifier similarto the following:

principal://iam.googleapis.com/projects/PROJECT/locations/global/workloadIdentityPools/POOL/subject/SUBJECT_ATTRIBUTE_VALUE

Federated access tokens are opaque and can't be introspected. The tokens can'tbe revoked and remain valid until expiry. The expiries for each token type areset as follows:

• Workforce Identity Federation sets the token expiry to the smaller of thefollowing two values:

  • Time left until the Workforce Identity Federation session expires

  • 1 hour

  The expiry of the Workforce Identity Federation session is determined based onthe time of sign-in and the session duration configured for theWorkforce Identity Federation pool.

• Workload Identity Federation sets the token expiry so that it matches the expiryof the external token.

Credential access boundary tokens

Credential access boundary tokens authenticate a user or service account andinclude an access boundary. Theaccess boundary restricts the token so that it can only be used to access adefined subset of Cloud Storage resources.

Credential access boundary tokens are sometimes referred to asdownscopedbecause they're derived from an input token, but are more restricted in theresources they grant access to.

The expiry of credential access boundary tokens is derived from the expiry ofthe input token, whichcan be auser access token orservice account access token. Credential access boundarytokens are opaque and they can't be introspected or revoked.

Client-issued credential access boundary tokens

Client-issued credential access boundary tokens are similar tocredential access boundary tokens, but areoptimized for scenarios in which clients need to obtain credential accessboundary tokens with different access boundaries at high frequency.

Clients can create client-issued credential access boundary tokens locally byusing the Cloud Client Libraries and an access boundary intermediary token,which they must refresh periodically.

Client-issued credential access boundary tokens are opaque and they can't beintrospected or revoked.

Token-granting tokens

Token-granting tokens allow clients to obtain new or different tokens, possiblyat a later time. Google Cloud supports multiple different types oftoken-granting tokens, and they all have the following in common:

• They represent a prior authentication.

• They authenticate a principal, which can be a Google identity (a user orworkload) or an external identity.

• They can be redeemed for an access token.

• They can't be used for making Google API calls, which distinguishes them fromaccess tokens.

Token-granting tokens can differ in the following ways:

• Issuer: The party that issues the token.

• Principal: The type of principal identity that the token can authenticate.

• Restrictions: The restrictions that can be imposed on the token.

The following table lists the different types of token-granting tokens.

The different types of token-granting tokens also exhibit different securityproperties:

• Format: Some tokens are opaque. Other tokens can be decoded by the client.

• Lifetime: Tokens differ in lifetime, and to what extent they can bemodified.

• Multi-use: Some token-granting tokens can only be used once. Other tokenscan be used multiple times.

• Revocability: Some tokens can be revoked. Other tokens remain valid untilexpiry.

The following table summarizes the differences between these properties fortoken-granting tokens:

Refresh tokens

Refresh tokens are opaque tokens that let clients obtain ID tokens and accesstokens for a user, if the user previously authorized a client to act on theirbehalf.

Refresh tokens are tied to a specific client and can only be used in combinationwith valid client credentials; for example, a client ID and client secret.

If the client's authorization includes one or moreGoogle Cloud OAuth scopes,then the lifetime of the refresh token is subject to theGoogle Cloud session lengthcontrol. Otherwise, refresh tokens remain valid until the user revokes theirauthorization or othertoken-revoking eventsoccur.

Authorization codes

Authorization codes are opaque, short-lived tokens.The codes are only intended to be used during user authentication as an intermediarybetween the client and the Google authorization server.

Likerefresh tokens, authorization codes are tied to a clientand can only be used in combination with valid client credentials. Unlikerefresh tokens, authorization codes can only be used once.

Federated refresh tokens

Federated refresh tokens are opaque tokens that let clients obtain accesstokens for a workforce identity pool principal, if the user previouslyauthorized a client to act on their behalf.

Likerefresh tokens, federated refresh tokens are tied to aspecific client and can only be used in combination with valid clientcredentials; for example, a client ID and client secret.

Unlike refresh tokens, federated refresh tokens can't be revoked. The lifetimeof a federated refresh token is linked to the workforce identity session thatwas used to obtain the token and it remains valid until the session expires.

Federated authorization codes

Likeauthorization codes, federated authorization codesare opaque, short-lived tokens.The codes are only intended to be used during user authentication as an intermediarybetween the client and the Google Cloud IAM authorization server.

Authorization codes are tied to a client, can only be used in combination withvalid client credentials, and can only be used once.

Service account JSON Web Token assertions

Service account JSON Web Tokens (JWTs) assertions assert the identity of aservice account. Workloads can use service account JWT assertions to obtainservice account access tokens ordomain-wide delegation tokens. The serviceaccount JWT assertion is signed by a service account key.

A decoded service account JWT assertion looks similar to the following, withSIGNATURE replaced by the token's signature:

{"alg":"RS256","kid":"290b7bf588eee0c35d02bf1164f4336229373300","typ":"JWT"}.{"iss":"service-account@example.iam.gserviceaccount.com","scope":"https://www.googleapis.com/auth/devstorage.read_only","aud":"https://oauth2.googleapis.com/token","exp":1744851267,"iat":1744850967}.SIGNATURE

Service account JWT assertions are structurally similar toservice account JWTs: both types of tokens can be issued by theclient itself, and are signed by a service account key. However, the two typesof tokens use different payloads, as described in the following table.

Service account JWT assertions can be valid up to one hour, and they can't berevoked.

External JSON Web Tokens

External JSON Web Tokens (JWTs) are issued by an external identity provider suchas Microsoft Entra ID, Okta, Kubernetes, or GitHub. They might differ in theirstructure and contents.

By configuring Workforce Identity Federation or Workload Identity Federation, you canset up a trust relationship between Google Cloud and an external identityprovider. Workloads can then use external JWTs as token-granting tokens toobtainfederated access tokens.

When you use Workforce Identity Federation, the resulting federated access tokenauthenticates aworkforce identity pool principal.

When you use Workload Identity Federation, the resulting federated access tokenauthenticates aworkload identity pool principal.

In both cases, the principal identifier is derived from one or more claims ofthe external JWT.

To be compatible with Workforce Identity Federation or Workload Identity Federation,external JWTs must satisfyspecific requirements.

External SAML assertions or responses

ExternalSecurity Assertion Markup Language(SAML) assertions are SAML 2.0 assertions that are issued by an externalidentity provider such as Microsoft Entra ID, Okta, or Active DirectoryFederation Services. These external SAML assertions can optionally be enclosedin a SAML 2.0 response or be encrypted.

Like withexternal JSON Web Tokens, you can configureWorkforce Identity Federation or Workload Identity Federation so that workloads can useexternal SAML assertions or responses as token-granting tokens to obtainfederated access tokens.

To be compatible with Workforce Identity Federation or Workload Identity Federation,external SAML assertions must satisfyspecific requirements.

Amazon Web Services (AWS)GetCallerIdentity token

External AWSGetCallerIdentity tokens are text blobs that contain a signedrequest to the AWSGetCallerIdentity API.Similar to external JSON Web Tokensand SAML assertions, you can configure Workforce Identity Federation or Workload Identity Federation sothat workloads can use these text blobs as a token-granting token to obtainfederated access tokens.

Identity tokens

Identity (ID) tokens let clients identify the user that they're interactingwith. Google Cloud supports multiple different types of identity tokens, andthey all have the following in common:

• They're formatted as JSON Web Tokens (JWTs) so that they can be decoded,verified, and interpreted by the client.

• They authenticate a principal, which can be a user or a workload.

• They're issued to one particular client.

• They're short-lived and expire after at most one hour.

• They're not revocable.

• They can't be used for making Google API calls, which distinguishes them fromaccess tokens.

• They can't be used to obtain access tokens, which distinguishes them fromtoken-granting tokens.

• They can be used to authenticatecalls between microservices, ortoprogrammatically authenticate toIdentity-Aware Proxy (IAP).

Identity tokens can differ in the following ways:

• Audience: The party that's intended to decode and consume the token.

• Issuer: The party that issues the token.

• Lifetime: The tokens differ in lifetime, and to what extent they can bemodified.

• Principal: The type of principal identity that the token can authenticate.

The following table lists the different types of identity tokens.

User ID tokens

User ID tokens are JSON Web Tokens (JWTs) that authenticate a user. Clients canobtain a user ID Token by initiating anOIDC authentication flow.

User ID tokens are signed using the Google JSON Web Key Set (JWKS). The GoogleJWKS is a global resource, and the same signing keys are used for differenttypes of users, including the following:

• Managed user accounts

• Consumer user accounts

• Service accounts

A decoded user ID token looks similar to the following, withSIGNATURE replaced by the token's signature:

{"alg":"RS256","kid":"c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9","typ":"JWT"}.{"iss":"https://accounts.google.com","azp":"1234567890-123456789abcdef.apps.googleusercontent.com","aud":"1234567890-123456789abcdef.apps.googleusercontent.com","sub":"12345678901234567890","at_hash":"y0LZEe-ervzRNSxn4R-t9w","name":"Example user","picture":"https://lh3.googleusercontent.com/a/...","given_name":"Example","family_name":"User","hd":"example.com","iat":1745361695,"exp":1745365295}.SIGNATURE

An ID token includes the following fields:

The exact set of claims included in an ID token depends on thescope parameterin the authentication request.

To identify whether a user is a managed user account, or to identify theCloud Identity or Google Workspace account a user belongs to, clients mustinspect thehd claim.

User ID tokens are valid for one hour, and can't be revoked.

Service account ID tokens

Service account ID tokens are JSON Web Tokens (JWTs) that authenticate a serviceaccount.

Unlikeservice account JWTs andservice account JWT assertions, service account ID tokensaren't signed by a service account key. Instead, service account ID tokens aresigned by the Google JSON Web Key Set (JWKS).

A decoded service account ID token looks similar to the following, withSIGNATURE replaced by the token's signature:

{"alg":"RS256","kid":"c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9","typ":"JWT"}.{"aud":"example-audience","azp":"112010400000000710080","email":"service-account@example.iam.gserviceaccount.com","email_verified":true,"exp":1745365618,"iat":1745362018,"iss":"https://accounts.google.com","sub":"112010400000000710080"}.SIGNATURE

A service account ID token includes the following fields:

The exact set of claims included in an ID token depends on the way the ID tokenis requested. For example, ID tokens requested by the Compute Enginemetadata server can optionally include additional claims thatassert the identity of the VM.ID Tokens requested by using theIAM Credentials APIcan optionally contain the organization ID of the service account's project.

Service account ID tokens are valid for one hour, and can't be revoked.

Identity-Aware Proxy assertions

Identity-Aware Proxy (IAP) assertions are JSONWeb Tokens (JWTs) that IAP passes toIAP-protected web applications in thex-goog-iap-jwt-assertionHTTP request header. IAP assertions authenticate a user and alsoserve as proof that a request was authorized by IAP.

• Managed user accounts

• Consumer accounts

• Service accounts

• Workforce identity pool principals

A decoded IAP assertion looks similar to the following, withSIGNATURE replaced by the token's signature:

If youconfigure IAP to use Workforce Identity Federationinstead of Google identities, IAP assertions look slightlydifferent:

{"alg":"ES256","typ":"JWT","kid":"4BCyVw"}.{"aud":"/projects/0000000000/global/backendServices/000000000000","azp":"/projects/0000000000/global/backendServices/000000000000","email":"user@example.com","exp":1745374290,"google":{"access_levels":["accessPolicies/0000000000/accessLevels/Australia"]},"iat":1745373690,"identity_source":"WORKFORCE_IDENTITY","iss":"https://cloud.google.com/iap","sub":"sts.google.com:AAFTZ...Q","workforce_identity":{"iam_principal":"principal://iam.googleapis.com/locations/global/workforcePools/example/subject/user-0000000000","workforce_pool_name":"locations/global/workforcePools/example"}}.SIGNATURE

An IAP assertion includes the following fields:

For further details about the IAP assertion claims, seeVerifying the JWT payload.

IAP assertions are valid for 10 minutes, and can't be revoked.

SAML assertions

Security Assertion Markup Language(SAML) assertions authenticate a managed user account and authorize them toaccess acustom SAML app. SAMLassertions are issued and signed by Cloud Identity and can only be used toauthenticate managed user accounts.

Unlike ID tokens which are signed by using global key, SAML assertions aresigned by using a key that is specific to a Cloud Identity orGoogle Workspace account.

A decoded SAML response assertion looks similar to the following:

<saml2:Assertionxmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"ID="..."IssueInstant="2025-04-23T22:47:20.881Z"Version="2.0"><saml2:Issuer>https://accounts.google.com/o/saml2?idpid=C0123456789</saml2:Issuer><ds:Signaturexmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature><saml2:Subject><saml2:NameIDFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">user@example.com</saml2:NameID><saml2:SubjectConfirmationMethod="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml2:SubjectConfirmationDataNotOnOrAfter="2025-04-23T22:52:20.881Z"Recipient="https://app.example.com/"/></saml2:SubjectConfirmation></saml2:Subject><saml2:ConditionsNotBefore="2025-04-23T22:42:20.881Z"NotOnOrAfter="2025-04-23T22:52:20.881Z"><saml2:AudienceRestriction><saml2:Audience>example-app</saml2:Audience></saml2:AudienceRestriction></saml2:Conditions><saml2:AuthnStatementAuthnInstant="2025-04-23T22:46:44.000Z"SessionIndex="..."><saml2:AuthnContext><saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef></saml2:AuthnContext></saml2:AuthnStatement></saml2:Assertion>

A SAML assertion includes the following fields:

The exact set of attributes included in a SAML assertion depends on the SAMLapp's configuration.

SAML assertions are valid for 10 minutes, and can't be revoked.