Configurer et utiliser Implement jeton d’actualisation multi-ressource

Configurez et mettez en œuvre les jetons d’actualisation multi-ressource Auth0 à l’aide de la Management API.

​

Configurer les applications pour MRRT

Pour utiliser les jetons d’actualisation multirésources (MRRT), configurez les politiques de jeton d’actualisation de votre application à l’aide de la Management API d’Auth0. Ces politiques préciseront quelles API et quelles portées l’application est autorisée à demander lors d’un échange de jeton d’actualisation.

Vous pouvez définir des politiques MRRT dans la propriété refresh_token.policies de l’application.

Propriété	Type	Description
audience	chaîne	L’identifiant de l’API Auth0 de l’application qui sera autorisée à utiliser le jeton d’actualisation.
scope	Tableau de chaînes	La liste des portées autorisées lors de la demande d’un jeton d’accès pour l’audience précisée. La portée doit être égale à celle définie pour l’API ou plus restrictive.

Les propriétés audience et scope doivent correspondre à une application existante dans votre tenant, sinon l’échange de jeton d’actualisation les ignorera sans avertissement.

Pour les applications existantes, envoyez une requête PATCH au point de terminaison Update a Client. Pour créer une nouvelle application, envoyez une requête POST au point de terminaison Create a Client :

Exemple de réponse :

{
  "client_id": "abc123xyz",
  "name": "My Native App",
  "refresh_token": {
    "rotation_type": "rotating",
    "policies": [
      {
        "audience": "https://api.example.com",
        "scope": ["read:data"]
      },
      {
        "audience": "https://billing.example.com",
        "scope": ["read:billing"]
      }
    ]
  }
}

​

Implement jeton d’actualisation multiressource

Une fois le jeton d’actualisation de votre application configuré avec des politiques MRRT, vous pouvez commencer à échanger un seul jeton d’actualisation contre des jetons d’accès pour plusieurs API. Pour ce faire, votre application doit amorcer un flux de connexion à l’aide soit du Flux de code d’autorisation, soit de l’Octroi de mot de passe du propriétaire de la ressource.

​

Étape 1 : S’authentifier et demander un jeton d’actualisation

Pour recevoir un jeton d’actualisation, incluez la portée offline_access lorsque vous lancez la requête d’authentification. Pour en savoir plus, consultez Obtenir des jetons d’actualisation.

Si vous ne recevez pas de jeton d’actualisation, vérifiez que :

• L’API a l’option Allow Offline Access activée dans ses paramètres.
• offline_access est inclus dans la portée.
• La valeur audience utilisée dans la requête correspond à une API configurée dans votre tenant.

​

Étape 2 : Échanger le jeton d’actualisation pour accéder à une autre API

Une fois le jeton d’actualisation émis, vous pouvez demander des jetons d’accès pour n’importe quelle API et toute portée définies dans l’authentification initiale et dans la politique MRRT. Par exemple :

 Pour en savoir plus, consultez Utiliser les jetons d’actualisation.

Si vous utilisez le SDK Auth0 Swift, vous pouvez échanger le jeton d’actualisation à l’aide du code suivant :

credentialsManager.apiCredentials(forAudience: "https://example.com/me",
                                  scope: "create:me:authentication_methods") { result in
    switch result {
    case .success(let apiCredentials):
        print("Obtained API credentials: \(apiCredentials)")
    case .failure(let error):
        print("Failed with: \(error)")
    }
}

Pour en savoir plus, consultez Auth0 Swift SDK.

Si vous utilisez l’Android SDK d’Auth0, vous pouvez échanger le jeton d’actualisation à l’aide du code suivant :

credentialsManager.getApiCredentials(
    audience = "https://example.com/me", scope = " create:me:authentication_methods",
    callback = object : Callback<APICredentials, CredentialsManagerException> {
        override fun onSuccess(result: APICredentials) {
            print("Obtained API credentials: $result")
        }
        override fun onFailure(error: CredentialsManagerException) {
            print("Failed with: $error")
        }
    })

Pour en savoir plus, consultez Auth0 Android SDK.

​

Étape 3 : Appeler l’API à l’aide du jeton d’accès

Utilisez le jeton d’accès pour faire une requête à l’API sécurisée au moyen du schéma d’autorisation HTTP Bearer. Pour en savoir plus, consultez Use Access Tokens.

Vous pouvez décoder le jeton d’accès sur jwt.io pour vérifier ce qui suit :

• Le champ aud correspond à l’API demandée. (par exemple : https://billing.example.com).
• Le champ scope inclut uniquement les valeurs autorisées.

​

Utiliser le jeton d’actualisation multi-ressource avec Actions

L’utilisation de MRRT avec Actions vous permet de configurer une prise de décision dynamique en fonction des politiques MRRT de l’application. À cette fin, les Actions post-login incluent l’objet event.client.refresh_token.policies, qui fournit des renseignements pertinents, notamment l’audience et la portée.

Vous pouvez utiliser l’objet event.client.refresh_token.policies pour évaluer l’audience et la portée de l’application au moment d’émettre ou d’échanger un jeton d’actualisation, et pour assurer un contrôle précis de l’accès à l’API et des portées.

exports.onExecutePostLogin = async (event, api) => {
  // retourner la liste des API autorisées dans le client
  const allowedAPIsInTheClient = event.client.refresh_token?.policies;

  if(allowedAPIsInTheClient?.some(policy => policy?.audience?.includes('https://myapi'))){
    // logique personnalisée
  }
};

​

Logique d’évaluation

Le MRRT agit comme une extension de l’authentification d’origine, et non comme un remplacement. Lors de l’échange d’un jeton d’actualisation, Auth0 évalue la requête d’échange selon la logique suivante :

• Si le paramètre audience est omis, Auth0 renvoie un jeton d’accès avec l’audience d’origine et toutes les portées supplémentaires configurées dans la politique MRRT.
• Si un nouveau paramètre audience est précisé, Auth0 vérifie que l’audience est incluse dans la politique MRRT et renvoie un jeton d’accès pour la nouvelle audience avec les portées configurées.
• Si le paramètre scope est omis, Auth0 combine toutes les portées autorisées de la requête d’origine et de la politique MRRT.
• Si un nouveau paramètre scope est précisé, Auth0 valide les portées demandées et renvoie un jeton d’accès avec les portées incluses dans la politique MRRT. Les portées demandées invalides ou non autorisées sont ignorées sans avertissement.
• Si le paramètre audience est identique à celui de la requête d’origine, Auth0 applique la politique MRRT et renvoie un jeton d’accès pour cette audience avec toutes les portées configurées par le MRRT ainsi que les portées de l’authentification d’origine.

Le MRRT vous permet d’étendre l’accès de l’utilisateur à de nouvelles API sans émettre de nouveaux jetons d’actualisation ni obliger l’utilisateur à ouvrir une nouvelle session.

​

Exemples

Un utilisateur ouvre une session en demandant l’audience et la portée suivantes :

{
"audience": "https://api.example.com",  
"scope": "openid profile read:messages"
}

La politique MRRT de l’application est configurée pour ajouter une portée supplémentaire :

{
  "audience": "https://api.example.com",
  "scope": ["write:messages"]
}

Un échange de jeton d’actualisation avec la même audience et sans portée donnerait un jeton d’accès contenant toutes les portées configurées :

{
  "aud": "https://api.example.com",
  "scope": "openid profile read:messages write:messages"
}