Configurer et mettre en œuvre le jeton d’actualisation multiresource

Découvrez comment configurer et mettre en œuvre le jeton d’actualisation multiresource

​

Configurer les applications pour MRRT

Pour utiliser les jetons d’actualisation multirésource (MRRT), configurez les politiques de jeton d’actualisation de votre application à l’aide de la Management API d’Auth0. Ces politiques précisent quelle API et quels scopes l’application peut 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	string	L’identifiant d’API Auth0 de l’application autorisée à utiliser le jeton d’actualisation.
scope	tableau de chaînes	La liste des scopes autorisés lors de la demande d’un jeton d’accès pour l’audience spécifiée. Le scope doit être identique à celui défini sur l’API ou plus restrictif.

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

Pour les applications existantes, effectuez un appel PATCH au point de terminaison Update a Client. Pour créer une nouvelle application, effectuez un appel 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"]
      }
    ]
  }
}

​

Implémenter un jeton d’actualisation multiresource

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 du flux de code d’autorisation ou 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 le scope offline_access lors de l’envoi de la demande 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’option Allow Offline Access est activée dans les paramètres de l’API.
• offline_access est inclus dans le scope.
• L’audience utilisée dans la demande correspond à une API configurée dans votre locataire.

​

Étape 2 : Échanger le jeton d’actualisation pour une autre API

Une fois le jeton d’actualisation émis, vous pouvez demander des jetons d’accès pour n’importe quelle API et les scopes définis à la fois dans l’authentification initiale et dans la stratégie MRRT. Par exemple :

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

Si vous utilisez le SDK Swift d’Auth0, 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 le SDK Swift Auth0.

Si vous utilisez le SDK Android 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 le SDK Android Auth0.

​

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

Utilisez le jeton d’accès pour appeler l’API sécurisée avec le schéma d’autorisation HTTP Bearer. Pour en savoir plus, consultez Utiliser des jetons d’accès.

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

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

​

Utiliser le jeton d’actualisation multiresource avec Actions

L’utilisation de MRRT avec Actions vous permet de configurer une logique décisionnelle dynamique en fonction des politiques MRRT de l’application. À cette fin, les Actions post-connexion incluent l’objet event.client.refresh_token.policies, qui fournit des renseignements pertinents, notamment l’audience et le scope.

Vous pouvez utiliser l’objet event.client.refresh_token.policies pour évaluer l’audience et le scope de l’application lors de l’émission ou de l’échange d’un jeton d’actualisation, afin d’assurer un contrôle précis de l’accès à l’API et des scopes.

exports.onExecutePostLogin = async (event, api) => {
  // retourner la liste des API autorisées dans l'application
  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 initiale, et non comme un remplacement. Lors de l’échange d’un jeton d’actualisation, Auth0 évalue la demande d’échange selon la logique suivante :

• Si le paramètre audience est omis, Auth0 renvoie un jeton d’accès avec l’audience initiale et tous les scopes supplémentaires configurés dans la stratégie MRRT.
• Si un nouveau paramètre audience est spécifié, Auth0 vérifie que l’audience est incluse dans la stratégie MRRT et renvoie un jeton d’accès pour la nouvelle audience avec les scopes configurés.
• Si le paramètre scope est omis, Auth0 combine tous les scopes autorisés de la demande initiale et de la stratégie MRRT.
• Si un nouveau paramètre scope est spécifié, Auth0 valide les scopes demandés et renvoie un jeton d’accès avec les scopes inclus dans la stratégie MRRT. Les scopes invalides ou non autorisés demandés sont ignorés sans avertissement.
• Si le paramètre audience est le même que dans la demande initiale, Auth0 applique la stratégie MRRT et renvoie un jeton d’accès pour l’audience avec tous les scopes configurés dans MRRT et les scopes de l’authentification initiale.

Le MRRT vous permet d’étendre l’accès de l’utilisateur à de nouvelles API sans émettre de nouveaux jetons d’actualisation ni lui demander de se reconnecter.

​

Exemples

Un utilisateur se connecte en demandant l’audience et le scope suivants :

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

La stratégie MRRT de l’application est configurée pour ajouter un scope supplémentaire :

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

Un échange de jeton d’actualisation avec la même audience et sans scope produirait un jeton d’accès contenant tous les scopes configurés :

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