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
. You can't create access tokens with an extended
lifetime for user credentials or external identities. 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 OIDC implementation, 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 Google
OAuth 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": "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 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)
Self-signed JWTs are required to
authenticate to APIs deployed with API Gateway
. In
addition, 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
By default, access tokens and ID tokens are valid for
1 hour. A refresh token is a special token that is used
to obtain additional access tokens or ID tokens. When your application first
authenticates, it receives an access token or ID token, as well as a refresh
token. Later, if the application needs to access resources again, and the
previously provided token has expired, it uses the refresh token to request a
new 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
, but
otherwise they continue to be usable. For user access in Google Workspace or
Cloud Identity premium edition, you can
configure the session length
to ensure that a user must log
in periodically to retain access to Google Cloud services.
If your application is creating and managing its own tokens, it also needs to
manage refresh tokens. For more information, see the following links:
Federated tokens
Federated tokens are used as an intermediate step by
workload identity federation
. Federated tokens are returned by the
Security Token Service
and cannot be used directly. They must be
exchanged for an access token
using service account
impersonation.
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.
If bearer tokens don’t provide sufficient security for your use case, consider
adding another layer of encryption or using a mutual Transport Layer Security
(mTLS) solution such as
BeyondCorp Enterprise
, which limits access to only
authenticated users on a trusted device.
What's next