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:

{
  "authentication": string,
  "authorization": string,
  "reason": string
}

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.

{
  "delegated_authentication": string
}

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...}"
}