Metodo: delegate
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Questa chiamata restituisce un nuovo token JWT (JSON Web Token) di autenticazione che consente
a un'entità di accedere a una risorsa specificata per conto dell'utente
autenticato nel JWT di autenticazione originale. Viene utilizzato per delegare
l'accesso con ambito a wrap o
unwrap a un'altra entità quando questa
deve agire per conto dell'utente.
Richiesta HTTP
POST https://<base_url>/delegate
Sostituisci <base_url> con l'URL del servizio di elenco di controllo dell'accesso per le chiavi (KACLS).
Parametri del percorso
Nessuno.
Corpo della richiesta
Il corpo della richiesta contiene una rappresentazione JSON della richiesta:
| Rappresentazione JSON |
{
"authentication": string,
"authorization": string,
"reason": string
}
|
| Campi |
authentication |
string
Un JWT emesso da una terza parte che dichiara l'identità dell'utente. Per maggiori dettagli, consulta la sezione relativa all'autenticazione.
|
authorization |
string
Un JWT con attestazioni delegated_to e resource_name che dichiarano che l'entità identificata dall'attestazione delegated_to è autorizzata ad accedere a resource_name per conto dell'utente. Per ulteriori informazioni, consulta Token di autorizzazione.
|
reason |
string (UTF-8)
Una stringa JSON passthrough che fornisce un contesto aggiuntivo sull'operazione. Il JSON fornito deve essere sanificato prima di essere visualizzato. Dimensioni massime: 1 kB.
|
Passaggi di elaborazione obbligatori
Il KACLS deve eseguire almeno questi passaggi:
- Convalida sia i token di autorizzazione sia quelli di autenticazione. Per maggiori informazioni, consulta Token di autorizzazione e Token di autenticazione.
- Verifica che i token di autorizzazione e autenticazione siano per lo stesso utente.
Per maggiori informazioni, vedi
Criptare e decriptare i dati.
- Verifica che l'attestazione
kacls_url nel token di autorizzazione corrisponda all'URL KACLS attuale. Ciò consente di rilevare potenziali server man-in-the-middle
configurati da insider o amministratori di domini non autorizzati.
- Se l'attestazione
kacls_owner_domain esiste nel token di autorizzazione, verifica
che il valore corrisponda al dominio Google Workspace del proprietario di KACLS. In questo modo
si impedisce a utenti non autorizzati di registrare il tuo KACLS su Google.
- Registra l'operazione, inclusi l'utente che l'ha originata,
delegated_to,
resource_name e il motivo indicato nella richiesta.
- Genera, firma e restituisce un token JWT contenente le rivendicazioni
delegated_to e
resource_name dal token di autorizzazione.
Il KACLS è libero di eseguire controlli di sicurezza aggiuntivi, inclusi quelli basati sulle rivendicazioni JWT.
Corpo della risposta
In caso di esito positivo, questo metodo restituisce un JWT di autenticazione contenente
le attestazioni delegated_to e resource_name. Questo token può essere utilizzato in un secondo momento per
l'autenticazione nelle chiamate ai metodi Wrap e Unwrap. In caso di errore, deve essere restituita una
risposta di errore strutturata.
| Rappresentazione JSON |
{
"delegated_authentication": string
}
|
| Campi |
delegated_authentication |
string
Un JWT di autenticazione delegata valido per l'accesso a resource_name da parte dell'utente menzionato nel JWT di autenticazione originale. Per maggiori informazioni, consulta Token di autenticazione KACLS per delegate.
|
Esempio
Richiesta
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'}"
}
Risposta
{
"delegated_authentication": "eyJhbGciOi...delegated_to_from_authz_token...resource_name_from_authz_token...}"
}
Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.
Ultimo aggiornamento 2025-07-26 UTC.
[null,null,["Ultimo aggiornamento 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 }"]]
