Autorisation utilisateur avec CIBA

Découvrez comment utiliser requête d’autorisation enrichi avec le flux backchannel initié par le client.

Pour utiliser les fonctionnalités de authentification backchannel initiée par le client (CIBA), vous devez avoir un plan Enterprise ou un module complémentaire approprié. Consultez Auth0 Pricing pour en savoir plus.

authentification backchannel initiée par le client (CIBA) est une spécification OAuth 2.0 qui permet à une application cliente d’initier un processus d’authentification et/ou un flux d’autorisation sans nécessiter d’interaction directe de l’utilisateur dans l’application d’origine. requête d’autorisation enrichi (RAR) est une extension OAuth 2.0 qui permet aux applications clientes de demander, dans une requête d’autorisation, des permissions plus complexes que les scopes OAuth 2.0 standard.

Vous pouvez utiliser CIBA avec RAR pour transmettre des données d’autorisation fine au serveur d’autorisation dans une requête backchannel. Le paramètre authorization_details contient des renseignements sur la requête que vous pouvez utiliser pour personnaliser l’invite de consentement affichée à l’utilisateur.

Vous pouvez autoriser les utilisateurs avec CIBA à l’aide des canaux de notification suivants :

• Notifications push mobiles à l’aide de l’application Auth0 Guardian et d’une application personnalisée intégrée au SDK Auth0 Guardian.
• Notifications par courriel, qui nécessitent la configuration d’une invite de consentement personnalisée.

​

Cas d’utilisation courants

Utilisez RAR avec le CIBA flow pour les cas d’utilisation qui exigent un contrôle plus fin de l’accès aux ressources. Parmi les cas d’utilisation courants :

1. Une application de paiement invite l’utilisateur à confirmer un transfert d’argent. Les authorization_details peuvent être personnalisés pour afficher les détails de la transaction.
2. Un agent d’IA présente à l’utilisateur les détails d’un rendez-vous médical reporté. Les authorization_details peuvent être personnalisés pour afficher la nouvelle heure et la nouvelle date.

​

Fonctionnement

Le flux d’autorisation de l’utilisateur avec CIBA ressemble au flux d’authentification de l’utilisateur avec CIBA, où la prise en charge de RAR permet aux clients de transmettre les authorization_details au serveur d’autorisation via le point de terminaison /bc-authorize.

Le diagramme de séquence suivant illustre le flux complet d’autorisation de l’utilisateur avec CIBA :

Les sections suivantes expliquent, étape par étape, le fonctionnement de l’autorisation de l’utilisateur avec CIBA.

• Prérequis
• Étape 1 : l’application cliente lance une requête CIBA
• Étape 2 : le tenant Auth0 accuse réception de la requête CIBA
• Étape 3 : l’application cliente interroge périodiquement pour obtenir une réponse
• Étape 4 : l’appareil d’authentification reçoit la notification push
• Étape 5 : l’appareil d’authentification récupère les détails du consentement
• Étape 6 : l’appareil d’authentification présente les détails du consentement à l’utilisateur
• Étape 7 : l’appareil d’authentification renvoie la réponse de l’utilisateur à Auth0
• Étape 8 : Auth0 reçoit la réponse de l’utilisateur une fois le flux terminé
• Étape 9 : Auth0 renvoie le jeton d’accès à l’application cliente

​

Prérequis

Pour lancer une requête CIBA avec Auth0, vous devez :

• Configurer l’authentification backchannel initiée par le client pour votre tenant et votre application, y compris votre canal de notification.
• Configurer les requête d’autorisation enrichi pour votre serveur de ressources, ce qui comprend l’enregistrement de vos types authorization_details.
• Si vous utilisez des notifications par courriel avec CIBA et RAR, définissez une invite de consentement personnalisée.

​

Étape 1 : L’application cliente lance une requête CIBA

Utilisez les API User Search pour trouver l’utilisateur qui autorise la requête pour lequel vous souhaitez lancer une requête CIBA et obtenir son ID utilisateur.

Une fois que vous avez l’ID utilisateur de l’utilisateur qui autorise la requête, utilisez l’Authentication API pour envoyer une requête CIBA avec authorization_details au point de terminaison /bc-authorize :

curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID}"}' \
  --data-urlencode 'audience=https://api.example.com' \
  --data-urlencode 'binding_message=Confirm payment of 2500' \
  --data-urlencode 'authorization_details=[{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]'

Paramètres	Description
tenant	Nom du tenant transmis dans la structure login_hint. Il peut aussi s’agir d’un domaine personnalisé. Si le format iss_sub est utilisé, le nom du tenant est transmis dans le claim iss. Exemple : login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID"}
client_id	Identifiant de l’application cliente.
client_secret	Méthode d’authentification du client utilisée pour l’authentification de l’utilisateur avec CIBA, par exemple Client Secret, Private Key JWT ou l’authentification mTLS. Si vous utilisez Private Key JWT ou mTLS, vous n’avez pas besoin d’inclure le client secret.
scope	Doit inclure openid. Le scope peut aussi inclure offline_access pour demander un refresh token. Toutefois, pour l’autorisation ponctuelle d’une transaction dans le flux CIBA, un refresh token n’est pas nécessaire et n’a aucune utilité dans ce contexte.
user_id	ID utilisateur de l’utilisateur qui autorise la demande, transmis dans la structure login_hint. Si le format iss_sub est utilisé, l’ID utilisateur est transmis dans le claim sub. Exemple : login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID}"} L’ID utilisateur peut avoir un format différent selon le fournisseur externe.
requested_expiry	L’expiration demandée du flux CIBA doit être comprise entre 1 et 259200 secondes (72 heures), et la valeur par défaut est de 300 secondes. Incluez le paramètre requested_expiry pour définir une expiration personnalisée pour le flux CIBA. Le paramètre requested_expiry aide à déterminer quel canal de notification CIBA utilise : Si vous définissez requested_expiry à 300 secondes ou moins, CIBA utilise le canal de notification mobile par push s’il est activé. Si vous n’avez pas configuré MFA pour votre tenant, la requête CIBA échoue. Si vous définissez requested_expiry à une valeur comprise entre 301 et 259200 secondes, CIBA utilise le canal de notification par courriel s’il est activé.
binding_message	Message lisible utilisé pour lier le flux CIBA entre l’appareil d’authentification et l’appareil utilisé pour consommer le service. Le message de liaison est obligatoire et ne peut pas dépasser 64 caractères. Utilisez uniquement des caractères alphanumériques et +-_.,:#
audience	Identifiant unique de l’audience du token émis.
authorization_details	Tableau JSON facultatif d’objets qui décrit les permissions à autoriser. Vous devez enregistrer la valeur type de chaque objet sur le serveur de ressources à l’aide du paramètre authorization_details du serveur de ressources. Pour en savoir plus, consultez configurer les requête d’autorisation enrichi.

​

Étape 2 : le tenant Auth0 reçoit la requête CIBA

Si le tenant Auth0 reçoit bien la requête POST, vous devriez recevoir une réponse contenant un auth-req-id associé à la requête :

{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}

La valeur auth_req_id est transmise à l’endpoint /token pour vérifier, à intervalles réguliers, si le CIBA flow est terminé.

​

Étape 3 : L’application cliente interroge périodiquement pour obtenir une réponse

Utilisez l’Authentication API pour appeler le point de terminaison /token à l’aide du type d’octroi urn:openid:params:grant-type:ciba et du auth_req_id reçu du point de terminaison /bc-authorize :

cURL

curl --location 'https://{YOUR_DOMAIN}.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'auth_req_id={AUTH_REQ_ID}' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

C#

var token = await authenticationApiClient.GetTokenAsync(
            new ClientInitiatedBackchannelAuthorizationTokenRequest()
            {
                AuthRequestId = response.AuthRequestId,
                ClientId = "your-client-id",
                ClientSecret = "your-client-secret"
            }
        );

Go

token, err := authAPI.OAuth.LoginWithGrant(context.Background(),
			"urn:openid:params:grant-type:ciba",
			url.Values{
				"auth_req_id":   []string{resp.AuthReqID},
				"client_id":     []string{clientID},
				"client_secret": []string{clientSecret},
			},
			oauth.IDTokenValidationOptions{})

Java

Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();

Jusqu’à ce que l’utilisateur chargé d’autoriser approuve la transaction, vous devriez recevoir la réponse suivante :

{
    "error": "authorization_pending",
    "error_description": "L'autorisation de l'utilisateur final est en attente"
}

Il faut attendre environ cinq secondes entre chaque requête de polling. Si vous effectuez le polling trop fréquemment, vous recevrez la réponse suivante, où la description varie selon l’intervalle de temporisation :

{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}

Pour résoudre l’erreur, attendez le prochain intervalle (en secondes) avant d’interroger de nouveau l’endpoint /token.

​

Étape 4 : l’appareil d’authentification reçoit la notification

Selon le canal de notification, Auth0 envoie une notification à l’appareil d’authentification :

• Notification push mobile : Auth0 l’envoie à l’application Auth0 Guardian ou à une application mobile personnalisée intégrant le SDK Auth0 Guardian.
• Notification par courriel : Auth0 l’envoie à l’adresse courriel vérifiée de l’utilisateur.

​

Étape 5 : l’appareil d’authentification récupère les détails du consentement

L’appareil d’authentification récupère les détails du consentement, c.-à-d. le contenu du binding_message, à partir de l’Auth0 Consent API :

• notification push mobile : l’application Auth0 Guardian ou une application personnalisée intégrée à l’Auth0 Guardian SDK appelle l’Auth0 Consent API pour récupérer les détails du consentement.
• Notification par courriel : lorsque l’utilisateur clique sur le lien de vérification, il est redirigé vers le navigateur, qui récupère les détails du consentement à partir de l’Auth0 Consent API.

​

Étape 6 : L’appareil d’authentification présente à l’utilisateur les détails du consentement

L’Auth0 Consent API renvoie à l’appareil d’authentification les détails du consentement, y compris binding_message, scope, audience et authorization_details, s’ils sont configurés. Les scopes renvoyés à l’application mobile sont filtrés selon votre politique RBAC. Pour en savoir plus, consultez Contrôle d’accès basé sur les rôles.

L’exemple de code suivant montre une réponse type de l’Auth0 Consent API :

{
  "id": "cns_2309dsfsd098",
  "requested_details": {
    "audience": "https://api.example.com",
    "scope": ["read:profile", "write:profile"],
    "binding_message": "abc123",
    "authorization_details": [
      {
        "type": "money_transfer",
        "instructedAmount": {
          "amount": 2500,
          "currency": "USD"
        },
        "sourceAccount": "xxxxxxxxxxx1234",
        "destinationAccount": "xxxxxxxxxxx9876",
        "beneficiary": "Hanna Herwitz",
        "subject": "A Lannister Always Pays His Debts"
      }
    ]
  },
  "created_at": 1632739200,
  "expires_at": 1632739200
}

L’appareil d’authentification présente à l’utilisateur les détails du consentement avec authorization_details :

• Notification push mobile : l’application Auth0 Guardian affiche authorization_details dans un écran de consentement au moyen d’une notification push.
• Notification par courriel : le navigateur affiche authorization_details dans un écran de consentement personnalisé. Pour savoir comment personnaliser l’écran de consentement, consultez Définir l’invite de consentement personnalisée.

L’utilisateur peut accepter ou refuser la demande d’autorisation à cette étape.

​

Étape 7 : L’appareil d’authentification renvoie la réponse de l’utilisateur à Auth0

Après que l’utilisateur a accepté ou refusé la demande d’autorisation, l’appareil d’authentification renvoie la réponse de l’utilisateur à Auth0 :

• Notification poussée mobile : l’application Auth0 Guardian ou une application personnalisée intégrée au SDK Auth0 Guardian renvoie la réponse de l’utilisateur à Auth0.
• Notification par courriel : le navigateur renvoie la réponse de l’utilisateur à Auth0.

​

Étape 8 : Auth0 reçoit la réponse de l’utilisateur une fois le flux terminé

L’application cliente met fin à l’interrogation périodique lorsqu’elle reçoit une réponse du point de terminaison /token. Un flux CIBA exige toujours une réponse — approbation ou refus — de la part de l’utilisateur autorisant, sans vérifier les autorisations déjà accordées. Cela signifie qu’Auth0 traite chaque requête CIBA comme une nouvelle autorisation de la part de l’utilisateur autorisant.

​

Étape 9 : Auth0 renvoie le jeton d’accès à l’application cliente

Si l’utilisateur refuse la demande push, Auth0 renvoie à l’application cliente une réponse d’erreur comme celle-ci :

{
    "error": "access_denied",
    "error_description": "L'utilisateur final a refusé la demande d'autorisation ou elle a expiré"
}

Si l’utilisateur approuve la demande push, Auth0 renvoie à l’application cliente un jeton d’accès contenant les authorization_details suivants :

{
  "id_token": "...",
  "access_token": "...",
  "expires_in": "...",
  "scope": "{SCOPES}",
  "authorization_details": [{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]
}

Le refresh_token n’est présent que si le scope offline_access a été inclus dans la requête initiale envoyée à /bc-authorize.

​

Interroger authorization_details

Au moment de la compilation, vous pouvez interroger le type et les objets de authorization_details à partir des détails du consentement de manière fortement typée, comme vous le feriez en interrogeant dynamiquement du JSON :

iOS

let requestedDetails: ConsentRequestedDetails = payload.requestedDetails
let myAuthorizationDetailsTypes = requestedDetails.authorizationDetails[0].objectValue!;
let type = myAuthorizationDetailsTypes["type"]?.stringValue // Votre valeur de type préenregistrée
let stringProperty = myAuthorizationDetailsTypes["string_property"]?.stringValue
let boolProperty = myAuthorizationDetailsTypes["bool_property"]?.boolValue
let numericProperty = myAuthorizationDetailsTypes["numeric_property"]?.doubleValue
let nestedObjectProperty = myAuthorizationDetailsTypes["nested_property"]?.objectValue
let nestedArrayProperty = myAuthorizationDetailsTypes["nested_array_property"]?.arrayValue

Android

RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
Map<String, Object> authorizationDetails = requestedDetails.getAuthorizationDetails().get(0);
String type = (String) myAuthorizationDetailsTypes.get("type");
String stringProperty = (String) myAuthorizationDetailsTypes.get("string_property");
boolean booleanProperty = (boolean) myAuthorizationDetailsTypes.get("boolean_property");
int numericProperty = (int) myAuthorizationDetailsTypes.get("numeric_property");
Object nestedObjectProperty = myAuthorizationDetailsTypes.get("nested_property");
List<Object> nestedArrayProperty = (List<Object>) myAuthorizationDetailsTypes.get("nested_array_property");

Si vous définissez un type personnalisé pour représenter votre objet, vous pouvez utiliser la fonction filterAuthorizationDetailsByType() pour renvoyer tous les objets authorization_details qui correspondent au type souhaité.

L’exemple de code suivant interroge authorization_details avec le type payment :

iOS

// Doit implémenter AuthorizationDetailsType 
struct Payment : AuthorizationDetailsType { 
static let type = "payment"; 
let amount: Double; 
let currency: String; 
} 

... 

let requestedDetails: ConsentRequestedDetails = payload.requestedDetails 
let payments = requestedDetails.filterAuthorizationDetailsByType(Payment.self) 
let firstPayment = payments.first!
let type: String = firstPayment.type // "payment" 
let amount: Double = firstPayment.amount 
let currency: String = firstPayment.currency

Android

@AuthorizatioDetailsType("payment")
class Payment {
    private String type;
    private int amount;
    private String currency;

    public Payment(String type, int amount, String currency) {
        this.type = type;
        this.amount = amount;
        this.currency = currency;
    }

    public String getType() {
        return type;
    }

    public int getAmount() {
        return amount;
    }

    public String getCurrency() {
        return currency;
    }
}

...

RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
List<Payment> payments = requestedDetails.filterAuthorizationDetailsByType(Payment.class);
Payment firstPayment = payments.get(0);
String type = firstPayment.getType();
int amount = firstPayment.getAmount();
String currency = firstPayment.getCurrency();

filterAuthorizationDetailsByType() renvoie uniquement les objets correspondant au type authorization_details spécifié. Par conséquent, votre application mobile devrait présenter à l’utilisateur tous les authorization_details pertinents pour le consentement, quel que soit leur type, afin d’assurer une compréhension complète de la requête.

Vous pouvez aussi interroger les authorization_details lorsque l’agent IA ou l’application interroge périodiquement le point de terminaison /oauth/token pour obtenir une réponse :

curl --request POST \
  --url "https://{YOUR_DOMAIN}.auth0.com/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:openid:params:grant-type:ciba" \
  --data-urlencode "client_id={YOUR_CLIENT_ID}" \
  --data-urlencode "client_secret={YOUR_CLIENT_SECRET}" \
  --data-urlencode "auth_req_id={AUTH_REQ_ID}"

Paramètres	Description
grant_type	Définissez-le sur le type d’autorisation CIBA : urn:openid:params:grant-type:ciba
client_id	Définissez-le sur le client ID de l’application.
client_secret	Définissez-le sur le client secret de l’application.
auth_req_id	Renvoyé par le tenant Auth0 lorsqu’il accuse réception de la requête CIBA. Fait référence à la requête CIBA.

Lorsque l’utilisateur qui autorise approuve la requête, Auth0 reçoit la réponse de l’utilisateur et le flux CIBA se termine en renvoyant un jeton d’accès et un tableau authorization_details :

{ 
  "access_token": "ey...ZQ", 
  "expires_in": 86400, 
  "authorization_details": [{ 
    "type": "money_transfer", 
    "instructedAmount": {
      "amount": 2500, 
      "currency": "USD"
    }, 
    "sourceAccount": "xxxxxxxxxxx1234", 
    "destinationAccount": "xxxxxxxxxxx9876", 
    "beneficiary": "Hanna Herwitz", 
    "subject": "A Lannister Always Pays His Debts" 
  }], 
  "token_type": "Bearer" 
}

​

Limitations

Auth0 ne prend pas en charge :

• La modification de RAR dans Actions pour les flux CIBA.
• La publication de types RAR pour que les clients puissent les découvrir, ce qui signifie que vous devez enregistrer au préalable les clients avec les types authorization_details qu’ils peuvent envoyer.
• La validation des objets RAR au-delà de la vérification qu’ils comportent une propriété type correspondant aux types autorisés pour l’API. Votre serveur de ressources est responsable de la validation granulaire du contenu de authorization_details. Pour en savoir plus, consultez Configurer RAR.

​

En savoir plus

• Configurer les requêtes d’autorisation enrichies (RAR)
• Flux du code d’autorisation avec les requêtes d’autorisation enrichies (RAR)
• Configurer l’authentification backchannel initiée par le client