Method: delegate

This call returns a new authentication JSON Web Token (JWT) that allows an entity to access a specified resource on behalf of the user authenticated in the original authentication JWT. It is used to delegate scoped access to wrap or unwrap to another entity when that entity needs to act on behalf of the user.

HTTP request

POST https://<base_url>/delegate

Replace <base_url> with the Key Access Control List Service (KACLS) URL.

Path parameters

None.

Request body

The request body contains a JSON representation of the request:

JSON representation 
{
  "authentication": string,
  "authorization": string,
  "reason": string
}
Fields
authentication

string

A JWT issued by a third-party asserting who the user is. See the authentication section for details.
authorization

string

A JWT with delegated_to and resource_name claims asserting that the entity identified by delegated_to claim is allowed to access resource_name on behalf of the user. For more information, see Authorization Tokens.
reason

string (UTF-8)

A passthrough JSON string providing additional context about the operation. The JSON provided should be sanitized before being displayed. Max size: 1 KB.

Required processing steps

The KACLS must perform at least these steps:

  • Validate both authorization and authentication tokens. For more information, see Authorization Tokens and Authentication Tokens.
  • Check that authorization and authentication tokens are for the same user. For more information, see Encrypt and decrypt data.
  • Check that the kacls_url claim in the authorization token matches the current KACLS URL. This allows detection of potential man-in-the-middle servers configured by insiders or rogue domain admins.
  • If the kacls_owner_domain claim exists in the authorization token, check that the value matches the KACLS owner's Google Workspace domain. This helps prevent unauthorized users from registering your KACLS with Google.
  • Log the operation, including the user originating it, the delegated_to, the resource_name, and the reason passed in the request.
  • Generate, sign, and return a JWT token containing delegated_to and resource_name claims from the authorization token.

The KACLS is free to perform additional security checks, including JWT claim based ones.

Response body

If successful, this method returns an authentication JWT containing delegated_to and resource_name claims. This token can later be used for authentication in calls to the Wrap and Unwrap methods. In case of an error, a structured error reply should be returned.

JSON representation 
{
  "delegated_authentication": string
}
Fields
delegated_authentication

string

A delegated authentication JWT valid for accessing resource_name by the user mentioned in the original authentication JWT. For more information, see KACLS authentication token for delegate.

Example

Request

POST https://mykacls.example.com/v1/delegate
{
  "authentication": "eyJhbGciOi...",
  "authorization": "eyJhbGciOi...delegated_to\":\"other_entity_id\",\"resource_name\":\"meeting_id\"...}",
  "reason": "{client:'meet' op:'delegate_access'}"
}

Response

{
  "delegated_authentication": "eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}"
}