Autorisation utilisateur avec CIBA

Pour utiliser les fonctionnalités d’authentification par canal arrière initiée par le client (CIBA), vous devez disposer d’un Enterprise Plan ou d’une option appropriée. Consultez Auth0 Pricing pour en savoir plus.

L’authentification par canal arrière initiée par le client (CIBA) est une spécification qui permet à une application cliente d’initier un flux d’authentification ou d’ sans interaction directe de l’utilisateur dans l’application qui initie la demande. Les demandes d’autorisation enrichies (RAR) constituent une extension d’OAuth 2.0 qui permet aux applications clientes de demander des autorisations plus complexes que les scopes OAuth 2.0 standards dans une requête d’autorisation. Vous pouvez utiliser CIBA avec RAR pour transmettre des données d’ au dans une requête par canal arrière. Le paramètre authorization_details contient des détails sur la requête que vous pouvez personnaliser dans une invite de consentement afin de les afficher à l’utilisateur. Vous pouvez autoriser des utilisateurs avec CIBA au moyen des canaux de notification suivants :

Notifications poussées 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 flux CIBA pour les cas d’utilisation qui exigent un contrôle plus précis de l’accès aux ressources. Parmi les cas d’utilisation courants :

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

Fonctionnement

Le flux d’autorisation de l’utilisateur avec CIBA est semblable au flux d’authentification de l’utilisateur avec CIBA, où la prise en charge de RAR permet aux applications clientes de transmettre authorization_details au serveur d’autorisation par l’intermédiaire du 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 locataire Auth0 accuse réception de la requête CIBA
Étape 3 : L’application cliente interroge périodiquement le serveur pour obtenir une réponse
Étape 4 : L’appareil d’authentification reçoit la notification poussée
É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 transmet 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 par canal arrière initiée par le client pour votre locataire et votre application, y compris votre canal de notification.
Configurer les demandes d’autorisation enrichies pour votre , y compris l’enregistrement de vos types authorization_details.
Si vous utilisez des notifications par courriel avec CIBA et RAR, configurez une invite de consentement personnalisée.

Étape 1 : L’application cliente lance une demande CIBA

Utilisez les API de recherche d’utilisateurs pour trouver l’utilisateur autorisant pour lequel vous souhaitez lancer une demande CIBA et obtenir son ID utilisateur. Une fois l’ID utilisateur de l’utilisateur autorisant obtenu, utilisez l’Authentication API pour envoyer une demande 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 locataire 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 locataire est alors transmis dans la revendication `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 de l’application utilisée pour authentifier l’utilisateur avec CIBA, par exemple Secret client, Private Key JWT ou l’authentification mTLS. Si vous utilisez Private Key JWT ou mTLS, vous n’avez pas besoin d’inclure le secret client.
`scope`	Doit inclure `openid`. Le scope peut aussi inclure `offline_access` pour demander un jeton d’actualisation. Toutefois, pour l’autorisation ponctuelle d’une transaction avec le flux CIBA, un jeton d’actualisation n’est pas nécessaire et n’a aucune utilité dans ce contexte.
`user_id`	ID utilisateur de l’utilisateur qui autorise, transmis dans la structure `login_hint`. Si le format `iss_sub` est utilisé, l’ID utilisateur est alors transmis dans la revendication `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`	La durée d’expiration demandée pour le 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 durée d’expiration personnalisée pour le flux CIBA. Le paramètre `requested_expiry` aide à déterminer quel canal de notification CIBA est utilisé : Si vous définissez `requested_expiry` à une valeur de 300 secondes ou moins, CIBA utilise le canal de notification poussée mobile s’il est activé. Si vous n’avez pas configuré MFA pour votre locataire, 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 en langage clair utilisé pour associer le flux CIBA entre les appareils d’authentification et de consommation. Le message de liaison est obligatoire et peut contenir jusqu’à 64 caractères. Utilisez uniquement des caractères alphanumériques et `+-_.,:#`
`audience`	Identifiant unique de l’audience du jeton émis.
`authorization_details`	Tableau JSON facultatif d’objets qui décrit les autorisations à accorder. Enregistrez 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 Configure Rich Authorization Requests.

Étape 2 : le locataire Auth0 confirme la réception de la requête CIBA

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

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

La valeur auth_req_id est transmise au point de terminaison /token pour interroger la fin du flux CIBA.

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

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

cURL
C#
Go
Java

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'

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

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{})

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

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

Tant que l’utilisateur qui autorise n’a pas approuvé la transaction, vous devriez recevoir la réponse suivante :

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

Il y a un intervalle d’attente d’environ cinq secondes entre chaque scrutation. Si vous effectuez la scrutation trop fréquemment, vous recevrez la réponse suivante, dans laquelle 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 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 poussée mobile : Auth0 l’envoie à l’application Auth0 Guardian ou à une application mobile personnalisée qui intègre le SDK Auth0 Guardian.
Notification par courriel : Auth0 l’envoie à l’adresse de courriel vérifiée de l’utilisateur.

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

Notification poussée mobile : L’application Auth0 Guardian ou une application personnalisée intégrée au SDK Auth0 Guardian appelle l’API Consent d’Auth0 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 depuis l’API Consent d’Auth0.

L’API Consent d’Auth0 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 conformément à votre stratégie de Contrôle d’accès basé sur les rôles. Pour en savoir plus, consultez Contrôle d’accès basé sur les rôles. L’exemple de code suivant présente une réponse type de l’API Consent d’Auth0 :

{
  "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 contenus dans authorization_details :

Notification poussée mobile : L’application Auth0 Guardian affiche authorization_details dans un écran de consentement au moyen d’une notification poussée.
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 une invite de consentement personnalisée.

À ce stade, l’utilisateur peut accepter ou refuser la demande d’autorisation.

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

Une fois que l’utilisateur a accepté ou refusé la demande d’autorisation, le appareil d’authentification renvoie sa réponse à 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 à la scrutation après avoir reçu 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, et les octrois existants ne sont pas vérifiés. Cela signifie qu’Auth0 traite chaque demande CIBA comme une nouvelle autorisation pour l’utilisateur autorisant.

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

Si l’utilisateur refuse la demande de notification push, Auth0 renvoie une réponse d’erreur semblable à la suivante à l’application cliente :

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

Si l’utilisateur approuve la demande de notification push, Auth0 renvoie à l’application cliente un contenant des authorization_details comme les 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 ne sera présent que si le scope offline_access a été inclus dans la requête initiale à /bc-authorize.

Interroger authorization_details

À la compilation, vous pouvez interroger le type et les objets de authorization_details à partir des détails de consentement de façon fortement typée, comme vous le feriez avec une interrogation dynamique de JSON :

iOS
Android

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

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 pour le type payment :

iOS
Android

// 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

@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() retourne uniquement les objets qui correspondent au type authorization_details spécifié. Par conséquent, votre application mobile devrait présenter à l’utilisateur tous les authorization_details pertinents pour obtenir son consentement, peu importe leur type, afin d’assurer une compréhension complète de la demande Vous pouvez aussi interroger authorization_details lorsque l’agent IA ou l’application interroge 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éfini sur le type d’octroi CIBA : `urn:openid:params:grant-type:ciba`
`client_id`	Défini sur l’ID client de l’application.
`client_secret`	Défini sur le secret client de l’application.
`auth_req_id`	Renvoyé par le locataire Auth0 lorsqu’il accuse réception de la demande CIBA. Fait référence à la demande CIBA.

Lorsque l’utilisateur qui autorise la demande l’approuve, Auth0 reçoit la réponse de l’utilisateur, et le flux CIBA se termine en renvoyant un jeton d’accès et le 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 des RAR dans Actions pour les flux CIBA.
La publication des types RAR pour qu’ils puissent être découverts par les applications; vous devez donc préenregistrer les applications avec les types authorization_details qu’elles peuvent envoyer.
La validation des objets RAR au-delà de la vérification de la présence d’une propriété type correspondant aux types autorisés pour l’API. Votre serveur de ressources est responsable de la validation fine du contenu de authorization_details. Pour en savoir plus, consultez Configure RAR.

​Cas d’utilisation courants

​Fonctionnement

​Prérequis

​Étape 1 : L’application cliente lance une demande CIBA

​Étape 2 : le locataire Auth0 confirme la 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

​Étape 5 : Le 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 : Le 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

​Interroger authorization_details

​Limitations

​En savoir plus

Cas d’utilisation courants

Fonctionnement

Prérequis

Étape 1 : L’application cliente lance une demande CIBA

Étape 2 : le locataire Auth0 confirme la 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

Étape 5 : Le 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 : Le 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

Interroger authorization_details

Limitations

En savoir plus