Configurer Rich Authorization Requests (RAR)

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

Grâce à Rich Authorization Requests (RAR), les clients peuvent demander et obtenir des données d’autorisation fine auprès des propriétaires de ressources, comme les utilisateurs finaux, pendant le flux du code d’autorisation avec des requêtes d’autorisation poussées (PAR) et le flux d’authentification backchannel initié par le client.

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 le client veut accéder au nom de l’utilisateur.

Vous pouvez présenter à l’utilisateur les authorization_details demandés de l’une des façons suivantes :

• Dans le navigateur, à l’aide d’une invite de consentement personnalisée
• Dans une application mobile, en utilisant des notifications push avec le SDK Auth0 Guardian ou l’application Auth0 Guardian

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

1. enregistrer les types authorization_details pour le serveur de ressources.
2. Configurer les politiques d’accès à l’API 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 politique 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 forme de l’objet. Un tableau authorization_details peut contenir plusieurs entrées du même type.

​

Auth0 Guardian app

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	Précise le type de demande d’autorisation : urn:auth0:schemas:authorization-details : l’URN Auth0 indique que la requête utilisera le schéma Auth0. v1 : la version du schéma. user-profile : valeur fournie par le client indiquant que la requête vise des renseignements du profil utilisateur.	urn:auth0:schemas:authorization-details:v1:user-profile
instruction	Message lisible par un humain invitant l’utilisateur à approuver la requête.	Please approve the request.
properties	Un objet JSON contenant les attributs utilisateur ou les claims précis demandés. Chaque clé (par exemple, 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é interne uniquement, non destinée à être vue par l’utilisateur. name : le nom lisible par un humain de la propriété (par exemple, “adresse 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 exemple, “[e-mail]”, “John Doe”). Le type de données peut varier (string, integer, boolean, 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 de votre propre application mobile personnalisée avec le SDK Auth0 Guardian, les exigences suivantes s’appliquent :

• Maximum de 5 Ko
• Doit être un 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 duquel l’argent sera transféré.
• destinationAccount : Le compte bancaire de destination vers lequel l’argent sera 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 les types authorization_details pour un serveur de ressources, ce qui est similaire à l’enregistrement des scopes autorisés. Vous pouvez enregistrer les types authorization_details à l’aide de l’Auth0 Dashboard ou 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 à votre serveur de ressources. Saisissez un type authorization_details.
4. Sélectionnez l’option +Add.

Vous pouvez voir les types authorization_details de 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 endpoint 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 endpoint /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 politiques d’accès à l’API

Les API Access Policies for Applications définissent quelles applications peuvent accéder à vos API et à quels scopes ou types authorization_details elles sont autorisées à accéder.

Vous pouvez vérifier la politique actuelle de votre API à l’aide de la Management API. Faites une requête GET au point de terminaison Get a resource server 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 accepte les valeurs client.policy et user.policy :

• Si la valeur de policy est allow_all, les applications ou les utilisateurs peuvent demander tous les types authorization_details enregistrés pour l’API.
• Si la valeur de policy est require_client_grant, chaque type de authorization_details doit alors être explicitement autorisé par le client grant pour cette application.
• Si la valeur de policy est deny_all, aucune application ni aucun utilisateur ne peut demander les types authorization_details enregistrés pour l’API.

Pour en savoir plus sur la gestion des client grants pour les applications, consultez Application Access to APIs: Client Grants .

​

Définir l’invite de consentement personnalisée

Vous pouvez afficher les authorization_details d’une requête d’autorisation enrichie 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 de l’Auth0 CLI ou de la Management API.

​

Auth0 CLI

Pour configurer les partials de consentement personnalisé, exécutez la commande auth0 ul customize avec les options appropriées dans votre terminal :

auth0 ul customize

Pour en savoir plus, consultez la documentation sur la personnalisation de Universal Login d’Auth0.

​

Management API

Pour configurer les partials de consentement personnalisé, 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 personnalisé suivante qu’Auth0 présente à l’utilisateur final :

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

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

• Personnaliser les pages Universal Login
• Personnaliser Universal Login avec l’éditeur No-Code
• Documentation de l’API Set partials for a prompt

​

Facultatif : Configurer la politique de consentement pour le serveur de ressources

La politique de consentement du serveur de ressources détermine si Auth0 stocke les valeurs authorization_details et les met à la disposition des applications mobiles lorsqu’une notification push est envoyée.

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

Flux	Notification push envoyée	Comportement
Tous	Non	L’invite de consentement personnalisée s’affiche.
Authorization Code Flow with PAR	Oui	Aucune invite de consentement ne s’affiche. Le consentement doit être affiché dans l’application mobile qui reçoit la demande d’approbation par 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 backchannel initié 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 exemple, dans un courriel), l’invite de consentement personnalisée s’affichera. Les clients peuvent choisir de déclencher une notification push 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 push envoyée	Comportement
Authorization Code Flow with PAR	Non	L’invite de consentement personnalisée s’affiche.
Authorization Code Flow with PAR	Oui	Aucune invite de consentement ne s’affiche. La solution du client doit afficher le consentement au moyen de sa propre interface utilisateur. Auth0 attribuera un ID unique à la requête et l’exposera à la Post-Login Action sous la forme de 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 push comprendra 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 backchannel initié par le client	Tous	Le flux CIBA n’est pas pris en charge avec la politique de consentement transactional-authorization-with-mfa

Vous pouvez définir la politique de consentement pour un serveur de ressources dans l’Auth0 Dashboard ou au moyen de la Management API.

Auth0 Dashboard

Définissez la politique 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 politique de consentement Standard.
4. Enregistrez vos modifications.

Management API

Pour définir la politique 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" }'