Method: delegate (original) (raw)

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 orunwrap 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, seeAuthorization Tokens andAuthentication Tokens.
Check that authorization and authentication tokens are for the same user. For more information, seeEncrypt 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 andresource_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 containingdelegated_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, astructured error replyshould 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...}"
}