GCP - Tokens

In the Google Cloud Platform (GCP) ecosystem, various types of tokens are used to manage authentication and authorization, ensuring secure access to resources and APIs. These tokens function as digital keys, each with a specific purpose, lifespan, and set of characteristics. Understanding the different token types is crucial for building secure and efficient applications on GCP.

Primary types of tokens used by GCP

Access Tokens

Access tokens are the most common type of token used to authorize calls to Google APIs. They are opaque, meaning their internal structure is not meant to be inspected by applications.

Purpose: To grant an application permission to access a user's or a service account's resources. They are used for authorization.
Format: Opaque strings that conform to the OAuth 2.0 framework.
How to Obtain: Typically, client libraries automatically handle the process of obtaining and refreshing access tokens. They can be obtained by exchanging credentials like a service account key or a user's refresh token. For resources running on GCP, the metadata service can provide them.
Lifetime: By default, access tokens are valid for one hour (3600 seconds). However, the lifetime can be customized for service accounts, up to a maximum of 12 hours.
Key Characteristic: They contain authorization information but do not carry identity information.

After obtaining an access token, applications include it in requests to Google APIs, typically in the Authorization HTTP header as a Bearer token.

ID Tokens

ID tokens are JSON Web Tokens (JWTs) that are used to verify the identity of a user or service account. Unlike access tokens, their contents are meant to be inspected and validated by the application.

Purpose: To authenticate a principal (a user or service account). They prove who the caller is.
Format: Signed JWTs that conform to the OpenID Connect (OIDC) specification. They consist of a header, payload (containing claims), and a signature.
How to Obtain: ID tokens can be obtained from the metadata server when running on certain GCP services, or by using the gcloud command-line tool. They can also be generated by exchanging other credentials, sometimes even an access token via the Service Account Credentials API.
Lifetime: By default, ID tokens are also valid for one hour.
Key Characteristic: The payload of an ID token contains "claims" such as the issuer (iss), the subject (sub - who the token was issued to), and the audience (aud - the intended recipient of the token). An application should always verify the aud claim to prevent token replay attacks.

Refresh Tokens

Refresh tokens are long-lived tokens used to obtain new access or ID tokens without requiring the user to go through the authentication and consent flow again.

Purpose: To maintain a long-term session with a user, allowing an application to get new, short-lived tokens on behalf of the user.
How to Obtain: A refresh token is typically issued along with the initial access token during the OAuth 2.0 authorization code flow. You will not usually get a refresh token again unless the user re-authorizes the application.
Lifetime: Refresh tokens are long-lived, but they can expire for several reasons, such as the user revoking access, or if the project is in the "Testing" phase (in which case they expire after 7 days). There are also limits on the number of refresh tokens per user account and client ID.
Key Characteristic: They are used almost exclusively for user authentication scenarios and are not typically associated with service accounts.

Bearer Tokens

The term "bearer token" is a general classification rather than a specific token type. It means that the "bearer" of the token (whoever possesses it) is granted access. Both access tokens and ID tokens in GCP are types of bearer tokens.

Usage: When making an API request, the bearer token is included in the Authorization header, like this: Authorization: Bearer <token>. This is a common practice when using tools like curl to interact with GCP services.

Self-Signed JWTs

Self-signed JWTs are used by service accounts to authenticate themselves and request an access token from Google's OAuth 2.0 server.

Purpose: To allow a service account to programmatically authenticate without a pre-existing access token.
How it Works: The application uses the service account's private key to sign a JWT. This signed JWT is then sent to Google's token service, which verifies the signature and, if valid, returns an access token.

Federated Access Tokens

These are a specialized form of access token used in identity federation scenarios.

Purpose: To allow workloads running outside of GCP (on-premises or in other clouds) or users from an external identity provider to access GCP resources.
How it Works: The Security Token Service exchanges external credentials for a short-lived federated access token.
Key Characteristic: These tokens are similar to standard access tokens but may have some limitations on which Google Cloud services they can be used with.

Token Exchange Flow

TL;DR:

third-party-identity token => [Secure Token Service] => Federated Access Token => [IAM Credentials API (generateAccessToken)] => Google Access Token

Step 1: Exchange Your External Token for a Federated Access Token

The first step is to take the credential you've received from your external IdP (like Azure AD, AWS, or an on-premises ADFS) and exchange it for a special, short-lived federated access token from Google's STS.

Here's what happens in this initial exchange:

Your Application's Role: Your application, running outside of GCP, first obtains an identity token (like an OIDC token or a SAML assertion) from its native IdP.
Calling the Security Token Service: Your application then makes a call to the Google STS API's v1/token endpoint.
What You Send to STS: In this request, you provide:
- The external identity token you just acquired.
- The audience for the token, which specifies the Workload Identity Pool and Provider you've configured in GCP.
- The grant_type which is typically urn:ietf:params:oauth:grant-type:token-exchange.
- The requested_token_type, which for this step is urn:ietf:params:oauth:token-type:access_token.
What STS Does: The STS verifies the external token against the configured IdP. If the token is valid, STS issues a short-lived federated access token. This token represents the federated identity within Google Cloud.

Step 2: Exchange the Federated Access Token for a Google Cloud Service Account Access Token

The federated access token you received in the first step proves your external identity to Google Cloud. However, to interact with most Google Cloud APIs, you need to act as a Google Cloud identity, which is a service account. This second exchange allows you to impersonate a service account.

Here's how this second exchange works:

Calling the IAM Credentials API: You now make a call to the generateAccessToken endpoint of the IAM Credentials API.
What You Send to IAM Credentials:
- The federated access token obtained from the STS in the Authorization header as a bearer token.
- The name of the Google Cloud service account you want to impersonate.
- The desired scopes for the final Google Cloud access token.
What IAM Credentials Does: The API checks if the federated identity (represented by your federated access token) has the roles/iam.workloadIdentityUser permission on the target service account.
The Final Prize: A Google Cloud Access Token: If the permissions are correct, the IAM Credentials API returns a standard, short-lived Google Cloud access token.

This final access token is what your application can then use to make authorized calls to other Google Cloud APIs, such as BigQuery, Cloud Storage, or Vertex AI, with the permissions of the impersonated service account.

Why this Multi-Step Process?

This layered approach enhances security:

No Long-Lived GCP Keys: You don't need to create, manage, or rotate long-lived service account keys on your external systems.
Principle of Least Privilege: You can grant very specific external identities the ability to impersonate particular service accounts, adhering to the principle of least privilege.
Centralized Auditing: Every token exchange is auditable within Google Cloud, providing a clear trail of who accessed what and when.
Short-Lived Credentials: All the tokens involved are short-lived, minimizing the risk if one is compromised.

In essence, by exchanging a federated access token for a Google Cloud access token, you are securely bridging the identity gap between your external environment and the Google Cloud ecosystem.