échange de jetons Privileged Worker avec Token Vault

Accordez à une application l’accès à Token Vault afin qu’elle puisse échanger un JWT bearer token contre un jeton d’accès pour appeler des API externes.

Token Vault prend en charge l’échange de jetons Privileged Worker, qui permet à une application cliente d’échanger un JWT signé (jeton de sujet) contre le jeton d’accès d’un fournisseur externe (requested token).

Après une authentification et une autorisation réussies de l’utilisateur, une application cliente transmet généralement le contexte utilisateur, qui contient l’identité de l’utilisateur, ses permissions et l’état de sa session, sous la forme d’un jeton d’accès ou d’actualisation pour effectuer l’échange de jetons avec Token Vault. Dans les flows de service à service, une application cliente, comme une application backend ou un service worker, peut avoir besoin d’accéder à des ressources au nom de l’utilisateur, mais puisque « l’utilisateur n’est pas présent » dans une session interactive, l’application cliente n’a pas accès au contexte utilisateur.

Dans ces scénarios de service à service, l’application cliente peut générer un JWT bearer token signé et l’utiliser comme jeton de sujet pour effectuer l’échange de jetons et recevoir les jetons nécessaires pour appeler des API externes. Cela signifie que l’application cliente peut effectuer des actions au nom de l’utilisateur sans interaction utilisateur active ni session.

Pour utiliser l’échange de jetons Privileged Worker avec Token Vault, l’application cliente doit être un client hautement privilégié qui peut demander des jetons d’accès à des fournisseurs externes par l’intermédiaire de Token Vault. Elle doit s’authentifier auprès de Token Vault à l’aide de méthodes cryptographiques asymétriques comme l’assertion Private Key JWT ou authentification TLS mutuelle.

​

Prérequis

Seuls certains types de clients peuvent utiliser Privileged Worker Token Exchange with Token Vault :

• Le client doit être un client propriétaire, c.-à-d. que la propriété is_first_party property doit être true.
• Le client doit être un client confidentiel avec un mécanisme d’authentification valide, c.-à-d. que la propriété token_endpoint_auth_method ne doit pas être définie sur none.
• Le client doit être conforme à OIDC, c.-à-d. que oidc_conformant doit être true.

Avant de configurer Privileged Worker Token Exchange pour votre application cliente :

1. Activez le type d’octroi Token Vault pour votre application cliente.
2. Configurez Private Key JWT ou l’authentification TLS mutuelle pour votre application cliente.

​

Configurer l’application cliente

Pour configurer l’accès privilégié de l’application cliente à Token Vault, vous devez :

• Fournir une clé publique servant à vérifier un JWT signé utilisé comme jeton de sujet.
• Restreindre les adresses IP à partir desquelles le client peut effectuer des requêtes.
• Limiter le client aux connexions et aux scopes qu’il est autorisé à demander.

Auth0 Dashboard

1. Accédez à Applications > Applications et sélectionnez votre application.
2. Sélectionnez l’onglet Settings, faites défiler la page jusqu’à la section Privileged Worker, puis activez Enable Privileged Worker. Dans la fenêtre modale, sélectionnez un identifiant de clé publique existant ou téléversez-en un nouveau, puis sélectionnez Save.
3. Une fois l’identifiant enregistré, saisissez au moins une adresse IP ou une plage CIDR dans le champ IP Allowlist.
4. Sous Permissions, sélectionnez Add Permission. Dans la fenêtre, sélectionnez une Connection et saisissez les Scopes que cette connexion est autorisée à demander, puis sélectionnez Save. Répétez l’opération pour chaque connexion que vous souhaitez autoriser. Vous pouvez configurer jusqu’à 5 permissions et 20 scopes au total.
5. Sélectionnez Save Changes.
6. Activez pour cette application chaque connexion référencée dans Permissions. Accédez à Authentication > [Connection type], sélectionnez la connexion, ouvrez l’onglet Applications, puis activez la connexion pour votre application.

Management API

Vous pouvez définir la clé publique, la liste d’autorisation d’adresses IP et les grants pour l’accès privilégié à Token Vault lors de la création d’un client. L’identifiant de clé publique se configure de façon semblable à la configuration de JAR :

POST https://{yourDomain}.auth0.com/api/v2/clients
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "name": "My App using Privilege Worker",
  "grant_types": [
    "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
  ],
  "oidc_conformant": true,
  "is_first_party": true,
  "jwt_configuration": {
    "alg": "RS256"
  },
  "token_vault_privileged_access": {
    "credentials": [
      {
        "name": "My credential for Token Vault Privileged Access",
        "credential_type": "public_key",
        "pem": "<YOUR_PEM_FILE_CONTENT>",
        "alg": "RS256"
      }
    ],
    "ip_allowlist": [
      "<YOUR_SERVER_IP_ADDRESS>"
    ],
    "grants": [
      {
        "connection": "<YOUR_CONNECTION_NAME>",
        "scopes": ["<YOUR_REQUIRED_SCOPE>"]
      }
    ]
  }
}

Vous pouvez également mettre à jour un client existant avec la clé publique, la liste d’autorisation d’adresses IP et les grants pour l’accès privilégié à Token Vault :

PATCH https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "token_vault_privileged_access": {
    "credentials": [{"id": "<YOUR_CREDENTIAL_ID>"}],
    "ip_allowlist": ["<YOUR_SERVER_IP_ADDRESS>"],
    "grants": [
      {
        "connection": "<YOUR_CONNECTION_NAME>",
        "scopes": ["<YOUR_REQUIRED_SCOPE>"]
      }
    ]
  }
}

L’id de l’identifiant est renvoyé dans la réponse lors de la création de votre client. Si vous devez le retrouver, récupérez-le au moyen d’une requête GET :

GET https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}/credentials
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>

Pour chaque connexion référencée dans grants, vous devez également activer la connexion pour ce client :

PATCH https://{yourDomain}.auth0.com/api/v2/connections/{yourConnectionId}/clients
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
[
  {
    "client_id": "<YOUR_CLIENT_ID>",
    "status": true
  }
]

La ip_allowlist (IP Allowlist dans le Dashboard) limite les adresses IP à partir desquelles des requêtes d’échange Privileged Worker peuvent être effectuées. Elle associe l’identifiant du client aux adresses IP de sortie connues du serveur, de sorte qu’un identifiant divulgué ne peut pas être utilisé depuis une adresse IP arbitraire. Les adresses IPv4 et IPv6, ainsi que les plages CIDR, sont prises en charge, jusqu’à un maximum de 10 entrées.

Les grants (Permissions dans le Dashboard) limitent le client à un ensemble précis de connexions et, pour chaque connexion, à un ensemble précis de scopes. Une requête d’échange de jetons Privileged Worker est rejetée si elle cible une connexion qui ne figure pas dans grants. De plus, si un scope plus restreint que celui accordé est demandé, Token Vault renvoie un token limité à ce scope, à condition que l’identity provider prenne en charge la restriction des scopes. Sinon, la requête échoue plutôt que de renvoyer silencieusement l’intégralité du scope accordé. Vous pouvez configurer un maximum de 5 connexions et de 20 scopes, toutes connexions confondues. Notez que la connexion indiquée doit être activée pour le client, comme décrit ci-dessus.

ip_allowlist et grants ne sont pas requis pour enregistrer la configuration d’un client, mais les deux doivent être renseignés pour que l’échange de jetons Privileged Worker fonctionne : toute requête provenant d’une adresse IP qui ne figure pas dans ip_allowlist, ou visant une connexion ou un scope qui ne figure pas dans grants, sera rejetée.

​

Créer un jeton de sujet JWT signé

Après avoir configuré votre application cliente avec la clé publique, vous devez créer le jeton de sujet qui sera échangé contre un jeton d’accès pour une API externe. Le jeton de sujet est un JSON Web Token (JWT) contenant les revendications nécessaires. Il est signé à l’aide de la clé privée.

Le JWT utilise un format et des revendications standards :

En-tête

Revendication	Description
typ	Obligatoire. Doit être token-vault-req+jwt.
kid	Facultatif. Nécessaire uniquement si plusieurs clés publiques sont configurées.

Charge utile

Revendication	Description
sub	Obligatoire. L’ID de l’utilisateur pour lequel vous souhaitez obtenir le jeton.
aud	Obligatoire. L’hôte de votre tenant.
iss	Obligatoire. L’ID de votre client qui effectue la requête.
iat	Obligatoire. Horodatage d’émission.
exp	Facultatif. Horodatage d’expiration. Les jetons datant de plus de 60 secondes sont rejetés dans tous les cas.
jti	Obligatoire. Un identifiant unique pour ce JWT (UUID v4 recommandé) afin de prévenir les attaques par rejeu.
audit_context	Obligatoire. Une chaîne lisible par l’humain (de 1 à 256 caractères) décrivant la raison opérationnelle de cet accès privilégié.
org_id	Facultatif. L’ID de l’organisation, si la requête est limitée à une organisation.

Voici un exemple de JWT :

{
    alg: "RS256"  
    typ: "token-vault-req+jwt"
}
.
{
    sub: "auth0|000012030101231",
    aud: "https://{yourDomain}.auth0.com/",
    iss: "<YOUR_CLIENT_ID>",
    iat: 1758799540,
    exp: 1758800540,
    nbf: 1758799540,
    jti: "<UNIQUE_JWT_ID>",
    audit_context: "<REASON_FOR_ACCESS>",
    org_id: "<YOUR_ORGANIZATION_ID>"
}

N’incluez pas de renseignements personnels identifiables (PII) dans audit_context. Cette valeur est consignée dans les journaux du tenant et peut être visible par les administrateurs et les destinations de diffusion des journaux.

L’exemple de code suivant est un script qui génère un jeton de sujet JWT signé :

import * as jwt from 'jsonwebtoken';
   const privateKey = ‘-----BEGIN RSA PRIVATE KEY-----........’;
   const subjectToken = jwt.sign(
     {
       iss: CLIENT_ID,
       aud: 'https://' + TENANT_DOMAIN + '/',
       sub: USER_ID,
       jti: uuidv4(),
       audit_context: 'Automated nightly sync for compliance report',
       // org_id est facultatif; incluez-le si cette requête est limitée à une organisation
       org_id: ORGANIZATION_ID,
     },
     privateKey,
     {
       algorithm: 'RS256',
       header: {
         typ: 'token-vault-req+jwt',
       },
     }
   );

​

Demander un jeton pour l’API externe

Une fois que vous avez le JWT signé, vous pouvez envoyer une requête pour obtenir le jeton d’accès à l’API externe :

curl --request POST 'https://{yourDomain}.auth0.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_SIGNED_JWT_BEARER>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "requested_token_type": "http://auth0.com/oauth/token-type/token-vault-access-token",
  "connection": "google-oauth2"
}'

Paramètre	Description
grant_type	Le type d’octroi. Pour Token Vault, définissez-le sur urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_id	ID de l’application cliente
client_secret	Secret du client. Remarque : Pour Privileged Worker Token Exchange, nous recommandons d’utiliser Private Key JWT ou l’authentification mTLS.
subject_token_type	Type du jeton de sujet. Pour Privileged Worker Token Exchange, définissez-le sur JWT : urn:ietf:params:oauth:token-type:jwt
subject_token	Le JWT bearer token signé que le serveur d’autorisation Auth0 valide pour identifier l’utilisateur.
requested_token_type	Le type de jeton demandé. Pour Privileged Worker Token Exchange, il doit toujours être http://auth0.com/oauth/token-type/token-vault-access-token.
connection	Le nom de la connexion, dans ce cas-ci, google-oauth2.