Token types

Cloud de Confiance by S3NS issues multiple types of tokens, which differ by their purpose and the parties they're exchanged between.

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

Access and identity tokens are bearer tokens. Bearer tokens are a general class of token that grant access to the party in possession of the token.

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, you can decrease the risk of token theft by using context-aware access, limiting the lifetime of access tokens, or by using a mutual Transport Layer Security (mTLS) solution such as Chrome Enterprise Premium.

Access tokens

Access tokens allow clients to make authenticated calls to Cloud de Confiance by S3NS APIs. Cloud de Confiance by S3NS supports multiple different types of access tokens, which have the following 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. This means that an access token typically doesn't grant access to all of a user's resources, 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 proprietary format and can't be inspected. Other tokens are encoded as a JSON Web Token, which can be decoded by the client.

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

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

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

Service account access tokens

Service account access tokens authenticate a service account. The tokens are opaque.

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

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "service-account@example.s3ns.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 the serviceAccounts.generateAccessToken method, you can request tokens with different lifetimes. Because longer token lifetimes can increase risk, you must configure the iam.allowServiceAccountCredentialLifetimeExtension constraint to allow clients to request service account access tokens with lifetimes longer than one hour.

Service account JSON Web Tokens

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

Sometimes these are called "self-signed" JWTs. They can be useful when you need to authenticate to some Google APIs without getting an access token from the authorization 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's email address, an OAuth scope or API endpoint, and an expiry time.

2. Sign the payload using a service account key of the respective service account. Clients can sign the payload offline by using a user-managed service account key, or online by using the signJwt method and a Google-managed service account key. For more information, see Create a self-signed JSON Web Token

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

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

Instead of specifying an OAuth scope in the scope key, a service account JWT can specify an API endpoint in the aud key:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.s3ns.iam.gserviceaccount.com",
  "sub": "service-account@example.s3ns.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 a workload identity pool principal.

Workforce Identity Federation lets clients exchange an external token against a federated access token that authenticates a workforce pool principal. The workforce identity pool principal is identified by a principal identifier similar to the following:

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

Workload Identity Federation lets clients exchange an external token against a federated access token that authenticates a workload pool principal. The workload identity pool principal is identified by a principal identifier similar to 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't be revoked and remain valid until expiry. The expiries for each token type are set as follows:

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

  • Time left until the Workforce Identity Federation session expires

  • 1 hour

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

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

Credential access boundary tokens

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

Credential access boundary tokens are sometimes referred to as downscoped because they're derived from an input token, but are more restricted in the resources they grant access to.

The expiry of credential access boundary tokens is derived from the expiry of the input token, which is a service account access token. Credential access boundary tokens are opaque and they can't be introspected or revoked.

Client-issued credential access boundary tokens

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

Clients can create client-issued credential access boundary tokens locally by using 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 be introspected or revoked.

Token-granting tokens

Token-granting tokens allow clients to obtain new or different tokens, possibly at a later time. Cloud de Confiance by S3NS supports multiple different types of token-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 or workload) 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 from access 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 security properties:

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

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

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

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

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

Federated refresh tokens

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

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

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

Federated authorization codes

Like authorization codes, federated authorization codes are opaque, short-lived tokens. The codes are only intended to be used during user authentication as an intermediary between the client and the Cloud de Confiance by S3NS IAM authorization server.

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

External JSON Web Tokens

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

By configuring Workforce Identity Federation or Workload Identity Federation, you can set up a trust relationship between Cloud de Confiance by S3NS and an external identity provider. Workloads can then use external JWTs as token-granting tokens to obtain federated access tokens.

When you use Workforce Identity Federation, the resulting federated access token authenticates a workforce identity pool principal.

When you use Workload Identity Federation, the resulting federated access token authenticates a workload identity pool principal.

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

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

External SAML assertions or responses

External Security Assertion Markup Language (SAML) assertions are SAML 2.0 assertions that are issued by an external identity provider such as Microsoft Entra ID, Okta, or Active Directory Federation Services. These external SAML assertions can optionally be enclosed in a SAML 2.0 response or be encrypted.

Like with external JSON Web Tokens, you can configure Workforce Identity Federation or Workload Identity Federation so that workloads can use external SAML assertions or responses as token-granting tokens to obtain federated access tokens.

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

Amazon Web Services (AWS) GetCallerIdentity token

External AWS GetCallerIdentity tokens are text blobs that contain a signed request to the AWS GetCallerIdentity API. Similar to external JSON Web Tokens, you can configure Workforce Identity Federation or Workload Identity Federation so that workloads can use these text blobs as a token-granting token to obtain federated access tokens.

Identity tokens

Identity (ID) tokens let clients identify the user that they're interacting with. Cloud de Confiance by S3NS supports multiple different types of identity tokens, and they 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 from access tokens.

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

• They can be used to authenticate calls between microservices, or to programmatically authenticate to Identity-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 be modified.

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

The following table lists the different types of identity tokens.

Service account ID tokens

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

Unlike service account JWTs and service account JWT assertions, service account ID tokens aren't signed by a service account key. Instead, service account ID tokens are signed by the Google JSON Web Key Set (JWKS).

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

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "aud": "example-audience",
  "azp": "112010400000000710080",
  "email": "service-account@example.s3ns.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 token is requested. For example, ID tokens requested by the Compute Engine metadata server can optionally include additional claims that assert the identity of the VM. ID Tokens requested by using the IAM Credentials API can 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 JSON Web Tokens (JWTs) that IAP passes to IAP-protected web applications in the x-goog-iap-jwt-assertion HTTP request header. IAP assertions authenticate a user and also serve 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, with SIGNATURE replaced by the token's signature:

{
  "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, see Verifying the JWT payload.

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