Método: delegate
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Essa chamada retorna um novo JSON Web Token (JWT) de autenticação que permite
que uma entidade acesse um recurso especificado em nome do usuário
autenticado no JWT de autenticação original. Usado para delegar
acesso limitado a wrap ou
unwrap a outra entidade quando ela
precisa agir em nome do usuário.
Solicitação HTTP
POST https://<base_url>/delegate
Substitua <base_url> pelo URL do serviço de lista de controle de acesso a chaves (KACLS, na sigla em inglês).
Parâmetros de caminho
Nenhum.
Corpo da solicitação
O corpo da solicitação contém uma representação JSON da solicitação:
| Representação JSON |
{
"authentication": string,
"authorization": string,
"reason": string
}
|
| Campos |
authentication |
string
Um JWT emitido por terceiros que afirma quem é o usuário. Consulte a seção de autenticação para mais detalhes.
|
authorization |
string
Um JWT com declarações delegated_to e resource_name que afirmam que a entidade identificada pela declaração delegated_to tem permissão para acessar resource_name em nome do usuário. Para mais informações, consulte Tokens de autorização.
|
reason |
string (UTF-8)
Uma string JSON de transmissão que fornece mais contexto sobre a operação. O JSON fornecido precisa ser limpo antes de ser exibido. Tamanho máximo: 1 KB.
|
Etapas de processamento necessárias
O KACLS precisa executar pelo menos estas etapas:
- Valide os tokens de autorização e autenticação. Para mais informações, consulte Tokens de autorização e Tokens de autenticação.
- Verifique se os tokens de autorização e autenticação são do mesmo usuário.
Para mais informações, consulte
Criptografar e descriptografar dados.
- Verifique se a declaração
kacls_url no token de autorização corresponde ao
URL atual do KACLS. Isso permite a detecção de possíveis servidores man-in-the-middle
configurados por pessoas de dentro da empresa ou administradores de domínio desonestos.
- Se a declaração
kacls_owner_domain existir no token de autorização, verifique se o valor corresponde ao domínio do Google Workspace do proprietário do KACLS. Isso ajuda a impedir que usuários não autorizados registrem seu KACLS no Google.
- Registre a operação, incluindo o usuário que a originou, o
delegated_to, o resource_name e o motivo transmitido na solicitação.
- Gere, assine e retorne um token JWT que contenha as declarações
delegated_to e resource_name do token de autorização.
O KACLS pode realizar outras verificações de segurança, incluindo as baseadas em declarações de JWT.
Corpo da resposta
Se for bem-sucedido, esse método vai retornar um JWT de autenticação com declarações de
delegated_to e resource_name. Esse token pode ser usado posteriormente para
autenticação em chamadas para os métodos Wrap e Unwrap. Em caso de erro, uma resposta de erro estruturada precisa ser retornada.
| Representação JSON |
{
"delegated_authentication": string
}
|
| Campos |
delegated_authentication |
string
Um JWT de autenticação delegada válido para acessar resource_name pelo usuário mencionado no JWT de autenticação original. Para mais informações, consulte Token de autenticação do KACLS para delegate.
|
Exemplo
Solicitação
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'}"
}
Resposta
{
"delegated_authentication": "eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}"
}
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-07-26 UTC.
[null,null,["Última atualização 2025-07-26 UTC."],[],[],null,["# Method: delegate\n\nThis call returns a new authentication JSON Web Token (JWT) that allows\nan entity to access a specified resource on behalf of the user\nauthenticated in the original authentication JWT. It is used to delegate\nscoped access to [wrap](/workspace/cse/reference/wrap) or\n[unwrap](/workspace/cse/reference/unwrap) to another entity when that\nentity needs to act on behalf of the user.\n\n### HTTP request\n\n`POST https://\u003cbase_url\u003e/delegate`\n\nReplace `\u003cbase_url\u003e` with the Key Access Control List Service (KACLS) URL.\n\n### Path parameters\n\nNone.\n\n### Request body\n\nThe request body contains a JSON representation of the request:\n\n| JSON representation ||\n|---------------------------------------------------------------------------------|---|\n| ``` { \"authentication\": string, \"authorization\": string, \"reason\": string } ``` |\n\n| Fields ||\n|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `authentication` | `string` A JWT issued by a third-party asserting who the user is. See the authentication section for details. |\n| `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](/workspace/cse/reference/authorization-tokens). |\n| `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. |\n\n### Required processing steps\n\nThe KACLS must perform at least these steps:\n\n- Validate both authorization and authentication tokens. For more information, see [Authorization Tokens](/workspace/cse/reference/authorization-tokens) and [Authentication Tokens](/workspace/cse/reference/authentication-tokens).\n- Check that authorization and authentication tokens are for the same user. For more information, see [Encrypt and decrypt data](/workspace/cse/guides/encrypt-and-decrypt-data).\n- 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.\n- 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.\n- Log the operation, including the user originating it, the `delegated_to`, the `resource_name`, and the reason passed in the request.\n- Generate, sign, and return a JWT token containing `delegated_to` and `resource_name` claims from the authorization token.\n\nThe KACLS is free to perform additional security checks, including JWT claim\nbased ones.\n\n### Response body\n\nIf successful, this method returns an authentication JWT containing\n`delegated_to` and `resource_name` claims. This token can later be used for\nauthentication in calls to the Wrap and Unwrap methods. In case of an error, a\n[structured error reply](/workspace/cse/reference/structured-errors)\nshould be returned.\n\n| JSON representation ||\n|------------------------------------------------|---|\n| ``` { \"delegated_authentication\": string } ``` |\n\n| Fields ||\n|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `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`](/workspace/cse/reference/authentication-tokens#kacls_authentication_token_for_delegate). |\n\n### Example\n\n#### Request\n\n POST https://mykacls.example.com/v1/delegate\n {\n \"authentication\": \"eyJhbGciOi...\",\n \"authorization\": \"eyJhbGciOi...delegated_to\\\":\\\"other_entity_id\\\",\\\"resource_name\\\":\\\"meeting_id\\\"...}\",\n \"reason\": \"{client:'meet' op:'delegate_access'}\"\n }\n\n#### Response\n\n {\n \"delegated_authentication\": \"eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}\"\n }"]]
