Accès interapplications (XAA) avec Token Vault

L’accès interapplications (XAA) permet aux administrateurs TI en contexte d’entreprise de gérer de façon centralisée les connexions application-à-application et agent-à-application. Token Vault fonctionne avec XAA pour stocker et réutiliser en toute sécurité les jetons d’accès que votre application récupère auprès d’une API tierce au nom d’un utilisateur. Avec Token Vault, votre application peut échanger un jeton d’actualisation Auth0 contre un jeton d’accès tiers stocké en une seule requête, sans obliger l’utilisateur à passer par un flux de consentement OAuth 2.0. Cet accès est plutôt géré par un fournisseur d’identité (IdP) centralisé auquel font confiance à la fois votre organisation et l’API tierce. Pour en savoir plus sur XAA dans Auth0, consultez Accès interapplications.

Si vous souhaitez créer et tester le flux XAA complet du côté de la Requesting App : suivez d’abord Configuration de l’environnement et Okta comme IdP OIDC, puis revenez ici pour configurer votre application de test.Si Token Vault est déjà configuré et que vous voulez ajouter la prise en charge de XAA : passez à Ajouter XAA à une intégration Token Vault existante.

Qu’est-ce qui change avec XAA?

Lorsque vous utilisez Token Vault avec XAA, les utilisateurs finaux n’ont pas à connecter leur compte à des applications externes. Votre application n’a pas besoin d’afficher un bouton « Se connecter à [Application tierce] » qui envoie une requête POST au endpoint /me/v1/connected-accounts/connect du My Account API.
L’utilisateur final doit s’authentifier au moyen d’un login fédéré avec une connexion Okta ou OIDC configurée pour XAA. Cette connexion doit être configurée à titre de Requesting App.
L’API tierce visée doit prendre en charge XAA en tant que Resource App, c’est-à-dire qu’elle peut échanger un ID-JAG contre des access tokens.
Une connexion à l’application tierce doit exister, avec les options Connected Accounts for Token Vault et Cross App Access for Token Vault activées.

Ajouter XAA à une intégration Token Vault existante

Si Token Vault est déjà configuré et que vous souhaitez y ajouter la prise en charge de XAA, vous devez mettre à jour deux connexions existantes : la connexion utilisée par vos utilisateurs pour s’authentifier (la connexion Requesting App) et la connexion à l’API third-party (la connexion Resource App).

Cette section porte uniquement sur les modifications à apporter du côté d’Auth0 pour activer XAA sur des connexions existantes. Si vous créez ces connexions pour la première fois ou que vous devez configurer le côté Okta, consultez Okta comme IdP OIDC pour la configuration end-to-end complète.

Configurer la connection de la Requesting App

La connection avec laquelle vos utilisateurs s’authentifient doit être configurée de façon à demander un ID-JAG à l’enterprise IdP au nom de l’utilisateur. Il peut s’agir d’une connection Okta Workforce ou OIDC.

Auth0 Dashboard
Management API

Allez à Authentication > Enterprise, sélectionnez votre connection, puis ouvrez ses paramètres.
Sous Credentials, réglez Communication Channel à Back Channel. Token Vault ne peut pas demander d’ID-JAG par le front channel.
Sous Settings > Scopes, ajoutez offline_access.
Sous Mappings, sélectionnez Okta Basic et ajoutez offline_access à la liste userinfo_scope du mapping JSON. Sélectionnez Save.
Sous Cross App Access > Cross App Access Role, sélectionnez Requesting Application.

Sélectionnez Save.

Effectuez une requête PATCH vers l’endpoint Update a Connection :

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{yourConnectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "cross_app_access_requesting_app": { "active": true },
    "options": {
      "scope": "openid profile email offline_access",
      "type": "back_channel",
      "attribute_map": {
        "mapping_mode": "use_map",
        "userinfo_scope": "openid email profile groups offline_access",
        "attributes": {
          "name": "${context.tokenset.name}",
          "email": "${context.tokenset.email}",
          "username": "${context.tokenset.preferred_username}",
          "federated_groups": "${context.userinfo.groups}",
          "federated_locale": "${context.userinfo.locale}",
          "federated_zoneinfo": "${context.userinfo.zoneinfo}"
        }
      }
    }
  }'

À la prochaine ouverture de session d’un utilisateur au moyen de cette connection, Token Vault conservera le refresh token et s’en servira pour demander l’accès à l’API third-party.

Configurer la connexion de la Resource App

La connexion de la Resource App à l’API third-party doit être une connexion OIDC dont les fonctionnalités Connected Accounts for Token Vault et accès interapplications pour Token Vault sont activées.

Auth0 Dashboard
Management API

Allez à Authentication > Enterprise, sélectionnez la connexion OIDC vers l’API third-party, puis ouvrez ses paramètres.
Sous Purpose, sélectionnez Connected Accounts for Token Vault ou Authentication and Connected Accounts for Token Vault.
Sous Cross App Access :
- Pour Cross App Access Roles, activez Requesting Application.
- Activez Cross App Access for Token Vault.

Sélectionnez Save.

Effectuez une requête PATCH vers l’endpoint Update a Connection :

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{yourConnectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "cross_app_access_requesting_app": { "active": true },
    "connected_accounts": {
      "active": true,
      "cross_app_access": true
    }
  }'

Une fois les deux connexions configurées, passez à Configurer votre application de test et testez le flow end-to-end.

Configurer votre application de test

Dans le tenant de votre Requesting App, créez ou configurez l’application qui effectuera le token exchange Token Vault.

Seuls les clients confidential, first-party et OIDC-conformant peuvent utiliser le Token Vault grant type. Les Regular Web Applications répondent à ces exigences.

Accédez à Applications > Applications, puis sélectionnez Create Application. Saisissez un nom et sélectionnez Regular Web Application.

Auth0 Dashboard
Management API

Sous Application URIs, ajoutez le callback URL de votre application (p. ex. https://localhost:3000/callback) aux Allowed Callback URLs.
Sous Cross App Access, activez Allow Cross App Access.
Sous Advanced Settings > Grant Types, activez Authorization Code, Refresh Token et Token Vault.
Sélectionnez Save Changes.

Faites une requête PATCH à l’endpoint Update a Client pour ajouter les grant types requis et activer l’accès interapplications :

curl --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "cross_app_access": { "active": true },
    "grant_types": [
      "authorization_code",
      "refresh_token",
      "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
    ]
  }'

Prenez note du Client ID et du Client Secret de l’application. Vous en aurez besoin au moment d’effectuer le token exchange.

Activer les connexions Okta pour l’application

Si vous avez configuré l’environnement de test XAA à partir de zéro du côté de la Requesting App : vous devez activer la connexion OIDC que vous avez configurée à l’étape Configuration de l’environnement entre le tenant de votre Requesting App et le tenant de votre Resource App, ainsi que la connexion Okta Workforce que vous avez configurée à l’étape Okta comme IdP OIDC pour cette application. Si vous avez déjà configuré Token Vault et que vous ajoutez la prise en charge de XAA : vous devez activer la connexion de la Requesting App et celle de la Resource App pour l’application de test que vous venez de créer. Pour en savoir plus, consultez Ajouter XAA à une intégration Token Vault existante.

Auth0 Dashboard
Management API

Pour activer la connexion Okta Workforce ou la connexion de la Requesting App :

Accédez à Authentication > Enterprise > Okta Workforce, sélectionnez la connexion Okta Workforce, puis sélectionnez l’onglet Applications. Activez-la ensuite pour l’application de test que vous venez de créer.

Pour activer la connexion OIDC ou la connexion de la Resource App :

Accédez à Authentication > Enterprise > OpenID Connect (OIDC), sélectionnez la connexion OIDC, puis sélectionnez l’onglet Applications. Activez-la ensuite pour l’application de test que vous venez de créer.

Effectuez une requête PATCH vers l’endpoint Update a Connection pour chaque connexion afin d’ajouter le client_id de l’application à l’array enabled_clients.Pour la connexion Okta Workforce :

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{oktaWorkforceConnectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "enabled_clients": ["{yourApplicationClientId}"]
  }'

Pour la connexion OIDC :

curl --request PATCH 'https://{yourDomain}/api/v2/connections/{oidcConnectionId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
  --data '{
    "enabled_clients": ["{yourApplicationClientId}"]
  }'

Tester le flow de bout en bout

Pour tester le flow XAA Token Vault, votre application doit :

Obtenir un refresh token Auth0 en réalisant un Authorization Code Flow avec la connection Okta Workforce ou la connection de la Requesting App.
Échanger le refresh token contre un access token de la Resource App avec la connection OIDC, à l’aide du Token Vault grant type ou de la connection de la Resource App.

Utilisez l’application de test que vous avez configurée à la section Configurer votre application de test, ou une application existante dont le grant Token Vault est activé.

Étape 1 : Obtenir un refresh token Auth0

Votre application utilise le flux du code d’autorisation avec la connexion Okta Workforce afin d’authentifier l’utilisateur et d’obtenir un refresh token.

Lancer l’authorization request

Envoyez la requête GET suivante à l’endpoint /authorize d’Auth0, en remplaçant les valeurs par les vôtres :

GET https://{yourRequestingAppDomain}/authorize?
  response_type=code&
  client_id={yourApplicationClientId}&
  redirect_uri={yourCallbackUrl}&
  scope=offline_access&
  connection={yourOktaWorkforceConnectionName} // ou le nom de la connection de votre Requesting App

Paramètre	Description
`response_type`	À définir à `code` pour utiliser le flux de code d’autorisation.
`client_id`	Le Client ID de l’application que vous avez configurée à la section Configurer votre application.
`redirect_uri`	Le callback URL de votre application. Il doit correspondre à un Allowed Callback URL configuré dans les paramètres de l’application.
`scope`	À définir à `offline_access` pour demander un refresh token.
`connection`	Le nom de la connection Okta Workforce que vous avez configurée à la section Okta comme IdP OIDC, ou la connection de la Requesting App.

Votre utilisateur de test sera redirigé vers Okta pour s’authentifier. Après un login réussi, Auth0 le redirige vers votre redirect_uri avec un code d’autorisation dans la query string.

Échanger le code d’autorisation contre un jeton d’actualisation

Envoyez une requête POST à l’endpoint Auth0 /oauth/token afin d’échanger le code d’autorisation contre des jetons :

curl -X POST 'https://{yourRequestingAppDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "code": "{authorizationCode}",
    "client_id": "{yourApplicationClientId}",
    "client_secret": "{yourApplicationClientSecret}",
    "redirect_uri": "{yourCallbackUrl}"
  }'

Paramètre	Description
`grant_type`	À définir à `authorization_code`.
`code`	Le code d’autorisation retourné par Auth0 une fois l’utilisateur authentifié.
`client_id`	Le Client ID de l’application.
`client_secret`	Le Client Secret de l’application.
`redirect_uri`	La même callback URL que celle utilisée dans la requête d’autorisation.

Une réponse réussie comprend un refresh_token :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "refresh_token": "v1.MjzFJHdw...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Étape 2 : Échanger le refresh token avec Token Vault

Utilisez le refresh token pour interroger l’endpoint du grant type Token Vault et obtenir un access token de la Resource App.

curl -X POST 'https://{yourRequestingAppDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{yourApplicationClientId}",
    "client_secret": "{yourApplicationClientSecret}",
    "subject_token": "{refreshToken}",
    "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
    "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "connection": "{yourOidcConnectionName}" // ou le nom de la connection de votre Resource App
  }'

Paramètre	Description
`client_id`	Le Client ID de l’application.
`client_secret`	Le Client Secret de l’application.
`subject_token`	Le refresh token Auth0 obtenu à l’étape 1.
`grant_type`	Le Token Vault grant type : `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token`.
`subject_token_type`	À définir à `urn:ietf:params:oauth:token-type:refresh_token` pour indiquer qu’un refresh token est échangé.
`requested_token_type`	À définir à `http://auth0.com/oauth/token-type/federated-connection-access-token` pour demander un access token de la Resource App.
`connection`	Le nom de la connection OIDC que vous avez configurée dans Environment Setup avec Cross App Access for Token Vault activé, ou la connection de la Resource App.

Token Vault utilise le XAA flow pour obtenir un access token vers la Resource App : il recherche un refresh token stocké provenant d’un IdP de Requesting App valide, demande à cet IdP un token ID-JAG en votre nom, puis le présente à la Resource App en échange d’un access token, qu’il retourne ensuite à votre application. Une response réussie retourne un access token de la Resource App :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Votre application peut désormais utiliser cet access token pour interroger l’API de la Resource App au nom de l’utilisateur.

Gérer plusieurs IdPs de Requesting App

Un tenant Auth0 peut compter de nombreuses connections configurées vers des IdPs qui prennent en charge XAA à titre de Requesting App et pour lesquelles XAA est activé (p. ex. leur propriété cross_app_access_requesting_app.active est définie à true). Lorsqu’une application effectue un token exchange request, Token Vault ne peut demander un ID-JAG qu’auprès d’un IdP auprès duquel l’utilisateur s’est déjà authentifié. Il doit exister une seule identity utilisateur valide liée au profile de l’utilisateur actuel, avec XAA activé sur la connection qui authentifie l’utilisateur; sinon, Token Vault ne saura pas à quel IdP demander un ID-JAG. S’il y a plusieurs identities valides, la request échouera avec l’erreur suivante :

{
    "error": "invalid_request",
    "error_description": "Multiple enterprise connections with XAA support enabled"
}

Si le profil de l’utilisateur actuel comporte plus de 10 identités liées sur des types de connexion qui prennent en charge XAA (soit les types de connexion Okta et OIDC) même si XAA n’est pas activé sur ces connexions, Token Vault échouera avec l’erreur suivante :

{
    "error": "invalid_request",
    "error_description": "User can have a maximum of 10 linked accounts to use XAA"
}

Cela limite le nombre de connections que le Token Vault doit vérifier pour repérer une connection XAA valide.

Utiliser Auth0 Organizations avec XAA

Token Vault filtrera également les connections de Requesting App disponibles pour ne conserver que celles qui sont activées pour l’organization de l’utilisateur actuel. Une solution Auth0 qui utilise Organizations peut limiter l’accès à chaque IdP par Organization afin de préciser quelle connection de Requesting App doit être utilisée pour chaque session utilisateur. Chaque subject_token utilisé dans un échange Token Vault contient de l’information sur l’organization dans laquelle l’utilisateur s’est connecté. Cet organization context servira à trouver la bonne connection de Requesting App XAA. Toutefois, si plusieurs connections valides sont trouvées, la request échouera tout de même.

Quickstarts

Auth0 Overview

Configure Auth0

Applications

Accès interapplications (XAA) avec Token Vault

Qu’est-ce qui change avec XAA?

Ajouter XAA à une intégration Token Vault existante

Configurer la connection de la Requesting App

Configurer la connexion de la Resource App

Configurer votre application de test

Activer les connexions Okta pour l’application

Tester le flow de bout en bout

Étape 1 : Obtenir un refresh token Auth0

Lancer l’authorization request

Échanger le code d’autorisation contre un jeton d’actualisation

Étape 2 : Échanger le refresh token avec Token Vault

Gérer plusieurs IdPs de Requesting App

Utiliser Auth0 Organizations avec XAA

​Qu’est-ce qui change avec XAA?

​Ajouter XAA à une intégration Token Vault existante

​Configurer la connection de la Requesting App

​Configurer la connexion de la Resource App

​Configurer votre application de test

​Activer les connexions Okta pour l’application

​Tester le flow de bout en bout

​Étape 1 : Obtenir un refresh token Auth0

​Lancer l’authorization request

​Échanger le code d’autorisation contre un jeton d’actualisation

​Étape 2 : Échanger le refresh token avec Token Vault

​Gérer plusieurs IdPs de Requesting App

​Utiliser Auth0 Organizations avec XAA

Qu’est-ce qui change avec XAA?

Ajouter XAA à une intégration Token Vault existante

Configurer la connection de la Requesting App

Configurer la connexion de la Resource App

Configurer votre application de test

Activer les connexions Okta pour l’application

Tester le flow de bout en bout

Étape 1 : Obtenir un refresh token Auth0

Lancer l’authorization request

Échanger le code d’autorisation contre un jeton d’actualisation

Étape 2 : Échanger le refresh token avec Token Vault

Gérer plusieurs IdPs de Requesting App

Utiliser Auth0 Organizations avec XAA