Configurer les Rich Authorization Requests (RAR)

Découvrez comment configurer les Rich Authorization Requests (RAR) pour un serveur de ressources.

Avec les Rich Authorization Requests (RAR), les applications peuvent demander et obtenir, auprès de propriétaires de ressources comme les utilisateurs finaux, des données d’autorisation fine dans le cadre du flux de code d’autorisation avec Pushed Authorization Requests (PAR) et du flux d’authentification par canal arrière initiée par le client.

Les Rich Authorization Requests utilisent le paramètre authorization_details. Ce paramètre accepte un tableau JSON d’objets pouvant inclure des renseignements détaillés sur l’autorisation demandée, comme les ressources précises ou les actions auxquelles l’application souhaite avoir accès au nom de l’utilisateur.

Vous pouvez afficher à l’utilisateur les authorization_details demandés en utilisant l’une des options suivantes :

• Le navigateur, en utilisant une invite de consentement personnalisée
• Une application mobile lors de l’utilisation de notifications poussées avec le SDK Auth0 Guardian ou l’application Auth0 Guardian

Pour configurer les Rich Authorization Requests pour un serveur de ressources, vous devez :

1. Enregistrer les types authorization_details pour le serveur de ressources.
2. Configurer les stratégies API Access pour permettre à votre application de demander ces types.
3. Définir l’invite de consentement personnalisée pour afficher les authorization_details.
4. Facultatif : configurer la stratégie de consentement pour le serveur de ressources.

​

Enregistrer les types authorization_details

Chaque objet du tableau JSON doit comporter un champ type qui décrit la structure de l’objet. Un tableau authorization_details peut contenir plusieurs entrées du même type.

​

Application Auth0 Guardian

Si vous utilisez l’application Auth0 Guardian, la valeur du paramètre authorization_details doit contenir un seul objet dans le tableau, et cet objet doit être conforme au schéma Auth0 suivant :

Field	Description	Example
type	Indique le type de demande d’autorisation : urn:auth0:schemas:authorization-details : l’URN Auth0 indique que la demande utilisera le schéma Auth0. v1 : la version du schéma. user-profile : valeur fournie par le client indiquant que la demande porte sur les renseignements du profil utilisateur.	urn:auth0:schemas:authorization-details:v1:user-profile
instruction	Un message en langage clair destiné à l’utilisateur pour approuver la demande.	Please approve the request.
properties	Un objet JSON contenant les attributs utilisateur ou les claims précis demandés. Chaque clé (par ex., email, full_name) représente un champ particulier du profil utilisateur : display : une valeur booléenne qui détermine si la propriété doit être affichée à l’utilisateur dans la boîte de dialogue de consentement. Si true, elle sera affichée; si false, il s’agit d’une propriété à usage interne seulement, qui n’est pas destinée à être vue par l’utilisateur. name : le nom en langage clair de la propriété (par ex., “Adresse de courriel”). display_order : un entier qui détermine l’ordre dans lequel les propriétés seront affichées dans la boîte de dialogue de consentement. description : une courte explication facultative de l’objectif de la propriété. value : la valeur réelle des données de la propriété (par ex., “[e-mail]”, “John Doe”). Le type de données peut varier (chaîne, entier, booléen, etc.).	"properties": { "stringPropertyForDisplay": { "display": true, "name": "A String:", "display_order": "1", "value": "Value 1"} }

Voici un exemple de type authorization_details utilisant le schéma Auth0 :

{
    "type": "urn:auth0:schemas:authorization-details:v1:user-profile",
    "instruction": "An instruction to the user",
    "properties": {
        "stringPropertyForDisplay": {
            "display": true,
            "name": "A String:",
            "display_order": 1,
            "value": "Value 1"
        },
        "numericPropertyForDisplay": {
            "display": true,
            "name": "A Number:",
            "display_order": 2,
            "description": "An optional description",
            "value": 100.00
        },
        "booleanPropertyForDisplay": {
            "display": true,
            "name": "A Boolean:",
            "display_order": 3,
            "value": true
        },
        "hiddenProperty": {
            "display": false,
            "value": "This value should not be displayed"
        }
    }
}

​

Autres canaux de notification

Le type authorization_details n’a pas besoin d’utiliser le schéma Auth0 si vous n’utilisez pas l’application Auth0 Guardian. Si vous affichez authorization_details au moyen d’une invite de consentement personnalisée ou dans votre propre application mobile avec le SDK Auth0 Guardian, les exigences suivantes s’appliquent :

• Maximum de 5 Ko
• Doit être du JSON valide
• Doit être un tableau d’objets
• Maximum de 5 entrées dans le tableau
• Chaque objet doit avoir une propriété type (préenregistrée dans l’API)
• Maximum de 10 propriétés par objet
• La longueur maximale des noms de propriété est de 255 caractères
• La longueur maximale de la valeur d’une propriété est de 255 caractères
• Maximum de 5 niveaux d’objets imbriqués
• Les noms de propriété ne peuvent contenir que les caractères suivants : a-zA-Z0-9_.-

Voici un exemple de authorization_details de type money_transfer qui n’utilise pas le schéma Auth0. Il contient les champs d’objet suivants :

• instructedAmount : Le montant en USD à transférer.
• sourceAccount : Le compte bancaire source à partir duquel l’argent doit être transféré.
• destinationAccount : Le compte bancaire de destination vers lequel l’argent doit être transféré.
• beneficiary : Le bénéficiaire du transfert d’argent.
• subject : L’objet du transfert d’argent.

{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}

Vous devez enregistrer des types authorization_details pour un serveur de ressources, ce qui est similaire à l’enregistrement des scopes autorisés. Vous pouvez enregistrer des types authorization_details dans l’Auth0 Dashboard ou au moyen de la Management API.

Auth0 Dashboard

Pour ajouter authorization_details dans l’Auth0 Dashboard :

1. Accédez à Auth0 Dashboard > Applications > APIs.
2. Sélectionnez l’onglet Permissions.
3. Sous Add an Authorization Details type, vous pouvez ajouter plusieurs types authorization_details pour votre serveur de ressources. Saisissez un type authorization_details
4. Sélectionnez l’option +Add.

Vous pouvez voir les types authorization_details pour votre serveur de ressources sous List of Authorization Details Types :

Management API

Pour enregistrer des types authorization_details pour un serveur de ressources existant, effectuez une requête PATCH vers le point de terminaison Update a resource server.

L’exemple de code suivant ajoute les types payment_initiation et money_transfer à authorization_details pour un serveur de ressources :

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
  }'

Pour créer un nouveau serveur de ressources avec un type authorization_details enregistré, effectuez une requête POST vers le point de terminaison /resource-servers.

La requête POST suivante crée un nouveau serveur de ressources avec le type authorization_details payment_initiation :

curl --location --request POST 'https://$tenant/api/v2/resource-servers' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Payments API",
  "identifier": "https://payments.api/",
  "authorization_details": [{"type": "payment_initiation"}]
  }'

​

Configurer les stratégies API Access

Les stratégies API Access pour les applications déterminent quelles applications peuvent accéder à vos API, ainsi que les scopes ou types authorization_details auxquels elles sont autorisées à accéder.

Vous pouvez vérifier la stratégie actuelle de votre API à l’aide de la Management API. Effectuez une requête GET vers le point de terminaison Obtenir un serveur de ressources et vérifiez la propriété subject_type_authorization dans la réponse :

curl --location --request GET 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json'

La propriété subject_type_authorization peut prendre des valeurs pour client.policy et user.policy :

• Si la valeur de la stratégie est allow_all, les applications ou les utilisateurs peuvent demander tous les types authorization_details enregistrés pour l’API.
• Si la valeur de la stratégie est require_client_grant, chaque type de authorization_details doit être explicitement autorisé par l’autorisation d’application de cette application.
• Si la valeur de la stratégie est deny_all, aucune application ni aucun utilisateur ne peut demander quelque type authorization_details que ce soit enregistré pour l’API.

Pour en savoir plus sur la gestion des autorisations d’application pour les applications, consultez Accès des applications aux API : Client Grants .

​

Définir l’invite de consentement personnalisée

Vous pouvez afficher les authorization_details d’une Rich Authorization Request dans l’invite de consentement. Pour ce faire, configurez l’invite customized-consent avec les partials de modèle appropriés.

Vous pouvez définir l’invite de consentement personnalisée à l’aide d’Auth0 CLI ou de la Management API.

​

Auth0 CLI

Pour configurer les partials du Consent personnalisé, exécutez la commande auth0 ul customize avec les indicateurs appropriés dans votre terminal :

auth0 ul customize

Pour en savoir plus, consultez la documentation sur Auth0 universal-login customize.

​

Management API

Pour configurer les partials de Customized Consent, envoyez une requête PUT au point de terminaison /prompts/customized-consent/partials :

curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
  --header "Authorization: Bearer $management_access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "customized-consent": {
      "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
    }
  }'

Le modèle de consentement personnalisé affiche authorization_details dans l’invite de consentement ci-dessous qu’Auth0 présente à l’utilisateur final :

Dans le flux de notifications par courriel avec CIBA et RAR, vous devez personnaliser l’invite de consentement pour afficher à l’utilisateur les écrans d’approbation ou de refus :

Pour en savoir plus sur la personnalisation de l’invite de consentement, consultez :

• Personnaliser les pages de Universal Login
• Personnaliser Universal Login avec l’éditeur sans code
• Définir des partials pour une invite dans la documentation de l’API

​

Optionnel : configurer la stratégie de consentement pour le serveur de ressources

La stratégie de consentement du serveur de ressources détermine si Auth0 stocke les valeurs authorization_details et les rend accessibles aux applications mobiles lorsqu’une notification poussée est envoyée.

Consultez le comportement de la stratégie de consentement standard d’Auth0 pour une requête contenant authorization_details :

Flux	Notification poussée envoyée	Comportement
Tous	Non	L’invite de consentement personnalisée s’affiche.
flux de code d’autorisation avec PAR	Oui	Aucune invite de consentement ne s’affiche. Le consentement doit être affiché dans l’application mobile qui reçoit le défi de notification push. Si l’application Auth0 Guardian est utilisée, elle affichera automatiquement les authorization_details à l’utilisateur. Si une application mobile personnalisée est utilisée, les authorization_details peuvent être récupérés à l’aide du SDK Auth0 Guardian.
flux d’authentification par canal arrière initiée par le client	Oui	Si l’application Auth0 Guardian est utilisée pour autoriser la requête CIBA, les authorization_details seront récupérés automatiquement et affichés. Si une application mobile personnalisée est utilisée pour autoriser la requête CIBA, les authorization_details peuvent être récupérés à l’aide du SDK Auth0 Guardian. Si la requête CIBA est autorisée au moyen d’un lien Web (par ex. depuis un courriel), l’invite de consentement personnalisée s’affichera. Les clients peuvent aussi choisir de déclencher une notification poussée comme second facteur pour la requête CIBA lorsque l’utilisateur l’approuve au moyen d’un lien Web; dans ce cas, le comportement est le même que ci-dessus. L’application Auth0 Guardian affiche automatiquement de nouveau les authorization_details à l’utilisateur, tandis que les applications mobiles personnalisées peuvent choisir de récupérer les authorization_details à l’aide du SDK Auth0 Guardian.

Les clients peuvent aussi définir consent_policy à transactional-authorization-with-mfa, ce qui entraîne le comportement suivant :

Flux	Notification poussée envoyée	Comportement
flux de code d’autorisation avec PAR	Non	L’invite de consentement personnalisée s’affiche.
flux de code d’autorisation avec PAR	Oui	Aucune invite de consentement ne s’affiche. La solution du client doit afficher le consentement dans sa propre interface utilisateur. Auth0 attribuera un identifiant unique à la requête et l’exposera à l’Action Post-Login sous la forme event.transaction.linking_id, ainsi que event.transaction.requested_authorization_details. Si l’application Auth0 Guardian est utilisée, les authorization_details ne seront PAS affichés. Si une application mobile personnalisée est utilisée, la notification poussée inclura le linking_id, ce qui permettra aux développeurs d’applications de récupérer les authorization_details à partir de leurs propres API, au besoin.
flux d’authentification par canal arrière initiée par le client	Tous	Le flux CIBA n’est pas pris en charge avec la stratégie de consentement transactional-authorization-with-mfa

Vous pouvez définir la stratégie de consentement d’un serveur de ressources dans l’Auth0 Dashboard ou à l’aide de la Management API.

Auth0 Dashboard

Définissez la stratégie de consentement dans les paramètres de votre API à l’aide de l’Auth0 Dashboard.

1. Accédez à Auth0 Dashboard > Applications > APIs.
2. Sélectionnez l’onglet Settings.
3. Sous Access Settings, choisissez la stratégie de consentement Standard.
4. Enregistrez vos modifications.

Management API

Pour définir la stratégie de consentement d’un serveur de ressources ou d’une API à l’aide de la Management API, envoyez une requête PATCH au point de terminaison Update a resource server. Dans la requête PATCH, définissez consent_policy à standard :

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "consent_policy": "standard" }'