Authentication tokens

Bearer token (JWT: RFC 7516) issued by the identity partner (IdP) to attest a user's identity.

JSON representation
{
  "aud": string,
  "email": string,
  "exp": string,
  "iat": string,
  "iss": string,
  "google_email": string,
  ...
}
Fields
aud

string

The audience, as identified by the IdP. Should be checked against the local configuration.

email

string (UTF-8)

The user's email address.

exp

string

Expiration time.

iat

string

Issuance time.

iss

string

The token issuer. Should be validated against the trusted set of authentication issuers.

google_email

string

An optional claim, to be used when the email claim in this JWT is different from the user's Google Workspace email ID. This claim carries the user's Google Workspace email identity.

...

Your Key Access Control List Service (KACLS) is free to use any other claims (location, custom claim, etc) to evaluate the perimeter.

KACLS authentication token for delegate

The authentication token contains a JSON Web Token (JWT) (JWT: RFC 7516) that is a bearer authentication token.

Sometimes a user is not able to authenticate on a client directly. In these cases the user can delegate their access to a specific resource to that client. This is achieved through issuing a new delegated authentication token that limits the scope of the original authentication token.

The delegated authentication token is similar to the ordinary authentication token with one additional claim:

claim
delegated_to

string

An identifier for the entity to delegate authentication to.

The resource_name claim in the authentication token is, in a delegation context, used for identifying the object encrypted by the Data Encryption Key (DEK) for which the delegation is valid.

The token is issued by the Key Access Control List Service (KACLS) using the Delegate call. It may be either self-signed JWTs that KACLS is able to validate, or KACLS may use any other IdP to do that, through a trusted call.

In order for the delegated authentication token to be considered valid, a delegated authorization token must be provided for the same operation. The delegated authorization token is similar to the ordinary authorization token, but contains the additional claim delegated_to. The values of the delegated_to and resource_name claims must match the values in the delegated authentication token.

We recommend that you set a lifetime value of 15 minutes for the delegated authentication tokens to avoid potential reuse in case of leakage.

JSON representation
{
  "email": string,
  "iss": string,
  "aud": string,
  "exp": string,
  "iat": string,
  "google_email": string,
  "delegated_to": string,
  "resource_name": string
  ...
}
Fields
email

string (UTF-8)

The user’s UTF-8 formatted email address.

iss

string

The token issuer, should be validated against the trusted set of authentication issuers.

aud

string

The audience, as identified by the IdP. Should be checked against the local configuration.

exp

string

Expiration time, should be checked.

iat

string

Issuance time, should be checked.

delegated_to

string

An identifier for the entity to delegate authentication to.

resource_name

string

An identifier for the object encrypted by the DEK, for which the delegation is valid.

...

The KACLS is free to use any other claims (location, custom claim, etc…) to evaluate the perimeter.

KACLS authentication token for PrivilegedUnwrap

Bearer token (JWT: RFC 7516) issued by the identity partner (IdP) to attest a user's identity.

This is only used on PrivilegedUnwrap. During PrivilegedUnwrap, if a KACLS JWT is used in place of an IDP authentication token, the recipient KACLS must first fetch the JWKS of the issuer, then verify the token signature, before checking the claims.

JSON representation
{
  "aud": string,
  "exp": string,
  "iat": string,
  "iss": string,
  "kacls_url": string,
  "resource_name": string
  ...
}
Fields
aud

string

The audience, as identified by the IdP. For Drive client-side encryption (CSE) PrivilegedUnwrap operations, this should be kacls-migration.

exp

string

Expiration time.

iat

string

Issuance time.

iss

string

The token issuer. Should be validated against the trusted set of authentication issuers. Must match the KACLS_URL of the requesting KACLS. The public key set of the issuer can be found at /certs.

kacls_url

string

URL of current KACLS, that the data is being decrypted on.

resource_name

string

An identifier for the object encrypted by the DEK. Maximum size: 128 bytes.

...

Your Key Access Control List Service (KACLS) is free to use any other claims (location, custom claim, etc) to evaluate the perimeter.