Notifications par courriel avec CIBA

Pour utiliser les fonctionnalités de Client-Initiated Backchannel Authentication (CIBA), vous devez disposer d’un Enterprise Plan ou d’un module complémentaire approprié. Consultez Auth0 Pricing pour plus de détails.

Lorsque vous utilisez des notifications par courriel avec CIBA, l’utilisateur reçoit un courriel contenant un lien qui le redirige vers son navigateur pour s’authentifier ou autoriser une requête. Avec les notifications par courriel dans CIBA, l’utilisateur ouvre une session sur l’appareil de consommation, mais termine l’authentification en cliquant sur un lien envoyé à son adresse courriel vérifiée. Lorsque l’utilisateur clique sur le lien de vérification, il est redirigé vers son navigateur, ce qui crée une session qu’Auth0 utilise pour suivre le processus d’authentification et confirmer l’identité de l’utilisateur. Cette session est nécessaire pour faire le lien entre l’appareil d’authentification, dans ce cas-ci le navigateur, et l’appareil de consommation, comme un téléviseur intelligent. Le diagramme suivant illustre le flux CIBA de bout en bout avec notifications par courriel :

Les sections suivantes expliquent, étape par étape, comment fonctionne l’authentification de l’utilisateur avec CIBA au moyen de notifications par courriel.

Prérequis
Étape 1 : L’application cliente amorce 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 : Auth0 envoie un lien à l’adresse courriel de l’utilisateur
Étape 5 : L’utilisateur s’authentifie dans le navigateur
Étape 6 : Le navigateur présente les détails du consentement à l’utilisateur
Étape 7 : Auth0 reçoit la réponse de l’utilisateur une fois le flux terminé
Étape 8 : Auth0 renvoie le jeton d’accès à l’application cliente

Prérequis

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

Configure Client-Initiated Backchannel Authentication pour votre tenant et votre application, y compris les notifications par courriel.
Définir le paramètre requested_expiry sur une valeur comprise entre 301 et 259200 secondes (72 heures). Pour en savoir plus, consultez Configurer le canal de notification.
Si vous utilisez les notifications par courriel avec CIBA et Rich Authorization Requests (RAR) pour l’autorisation de l’utilisateur, configurez l’invite de consentement personnalisée.

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

Utilisez les API User Search pour trouver l’utilisateur qui autorise la demande, pour lequel vous souhaitez lancer une demande CIBA, et obtenir son ID utilisateur. Une fois que vous avez l’ID utilisateur de l’utilisateur qui autorise la demande, utilisez l’API d’authentification ou nos SDKs pour envoyer une demande CIBA au point de terminaison /bc-authorize :

cURL
C#
Go
Java

curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
  --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 'scope={SCOPES}' \
  --data-urlencode 'binding_message={BINDING_MESSAGE}'

var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
            new ClientInitiatedBackchannelAuthorizationRequest()
            {
                ClientId = "{YOUR_CLIENT_ID}",
                Scope = "{SCOPES}",
                ClientSecret = "{YOUR_CLIENT_SECRET}",
                BindingMessage = "{BINDING_MESSAGE}",
                LoginHint = new LoginHint()
                {
                    Format = "iss_sub",
                    Issuer = "https://{YOUR_DOMAIN}.auth0.com/",
                    Subject = "{USER_ID}"
                }
            }
        );

resp, err := authAPI.CIBA.Initiate(context.Background(), ciba.Request{
    ClientID:     mgmtClientID,
    ClientSecret: mgmtClientSecret,
    Scope:        "openid",
    LoginHint: map[string]string{
      "format": "iss_sub",
      "iss":    "https://{YOUR_DOMAIN}.auth0.com/",
      "sub":    "{USER_ID}",
    },
    BindingMessage: "{BINDING_MESSAGE}",
  })

//Création d’une instance AuthClient
AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

//Autorisation
Map<String, Object> loginHint = new HashMap<>();
        loginHint.put("format", "iss_sub");
        loginHint.put("iss", "https://{YOUR_DOMAIN}.auth0.com/");
        loginHint.put("sub", "{USER_ID}");

Request<BackChannelAuthorizeResponse> request = auth.authorizeBackChannel("openid", "{BINDING_MESSAGE}", loginHint);

BackChannelAuthorizeResponse resp = request.execute().getBody();

Paramètres	Description
`tenant`	Nom du tenant. Il peut aussi s’agir d’un domaine personnalisé. Si le format `iss_sub` est utilisé, le nom du tenant est transmis dans la claim `iss`.
`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, comme 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, dans le cas d’une autorisation ponctuelle d’une transaction avec le CIBA Flow, un refresh token n’est pas nécessaire et n’a aucune utilité dans ce contexte.
`user_id`	ID de l’utilisateur autorisant, transmis dans la structure `login_hint`. Si le format `iss_sub` est utilisé, l’ID de l’utilisateur est transmis dans la claim `sub`. L’ID de l’utilisateur peut avoir un format différent selon le fournisseur externe.
`requested_expiry`	La durée maximale, en secondes, pendant laquelle la session CIBA doit rester valide. La durée d’expiration demandée pour le CIBA Flow 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 CIBA Flow. 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 push mobile s’il est activé. Si MFA n’est pas configuré pour votre tenant, la CIBA request échoue. Si vous définissez `requested_expiry` à une valeur comprise entre 301 et 259200 secondes (72 heures), CIBA utilise le canal de notification par courriel s’il est activé.
`binding_message`	Message lisible par une personne servant à lier le CIBA Flow 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 `+-_.,:#`.

Il existe une limite de débit propre à l’utilisateur selon laquelle l’utilisateur autorisant ne recevra pas plus de 5 requêtes par minute.

Étape 2 : le tenant Auth0 confirme la réception de 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 qui renvoie à la requête :

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

La valeur auth_req_id est transmise au endpoint /token pour vérifier périodiquement si le CIBA flow est terminé.

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

Utilisez l’Authentication API ou nos SDKs pour envoyer une requête au point de terminaison /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 point de terminaison /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 autorisant 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 délai d’attente d’environ cinq secondes entre chaque interrogation périodique. Si vous interrogez le point de terminaison trop fréquemment, vous recevrez la réponse suivante, où la description varie selon l’intervalle de temporisation progressive :

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

Pour corriger l’erreur, attendez le prochain intervalle (en secondes) avant d’interroger le point de terminaison /token.

Étape 4 : Auth0 envoie un lien à l’adresse courriel de l’utilisateur

Auth0 Authorization Server utilise le login_hint, qui contient l’ID utilisateur de l’utilisateur autorisant, pour lancer l’authentification de l’utilisateur sur l’appareil d’authentification :

Auth0 Authorization Server envoie un courriel à l’adresse courriel vérifiée de l’utilisateur.
Le courriel contient un lien de vérification sur lequel l’utilisateur doit cliquer pour s’authentifier. Le binding_message s’affiche comme code de requête.
Le lien redirige l’utilisateur vers le navigateur au moyen d’une requête à l’endpoint /bc-verify, où le paramètre de requête consent renvoie à la requête CIBA en attente de consentement.

Auth0 envoie un courriel à l’adresse courriel vérifiée de l’utilisateur

Étape 5 : L’utilisateur s’authentifie dans le navigateur

Si aucune session active n’est trouvée, le lien de vérification demandera à l’utilisateur de s’authentifier. L’utilisateur clique sur le lien pour poursuivre le processus d’authentification. Pour s’authentifier, l’utilisateur saisit son adresse courriel vérifiée et son mot de passe. L’utilisateur doit utiliser les informations d’authentification fournies au paramètre login_hint envoyé au point de terminaison /bc-authorize lorsque l’application cliente initie une demande CIBA. Sinon, un message d’erreur s’affiche et l’utilisateur doit se déconnecter et réessayer.

Comme dans un flux de connexion standard, le déclencheur Actions post-login s’exécute dans le flux CIBA avec courriel, ce qui permet aux clients d’ajouter une logique personnalisée pour appliquer des politiques de contrôle d’accès ou demander des facteurs MFA supplémentaires. Lorsqu’il est exécuté à partir d’un lien de vérification CIBA, la valeur event.transaction.protocol est oidc-ciba-web-link, ce qui vous permet d’appliquer des règles personnalisées à ce type précis de connexion. Pour en savoir plus, consultez Déclencheur de connexion. Une fois l’authentification réussie, le navigateur présente à l’utilisateur les détails de consentement provenant de l’Auth0 Consent API, y compris binding_message, scope et audience. Les scopes sont filtrés selon votre politique RBAC. Pour en savoir plus, consultez Role-Based Access Control. L’exemple de code suivant montre une réponse de l’Auth0 Consent API :

{
  "id": "cns_abc123",
  "requested_details": {
    "audience": "https://$tenant.auth0.com/userinfo",
    "scope": ["openid"],
    "binding_message": "21-49-38"
  },
  "created_at": 1746693720
  "expires_at": 1746693750
}

L’utilisateur peut accepter ou refuser la requête d’authentification à ce stade-ci.

Étape 6 : Le navigateur renvoie la réponse de l’utilisateur à Auth0

Le navigateur renvoie la réponse de l’utilisateur à Auth0. Selon que l’utilisateur accepte ou rejette la requête d’authentification, Auth0 affiche les écrans de consentement suivants, que vous devez personnaliser en définissant les invites de consentement :

L’utilisateur accepte la requête d’authentification

L’utilisateur refuse la requête d’authentification

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

L’application cliente met fin à l’interrogation dès qu’elle reçoit une réponse de l’endpoint /token. Un flux CIBA exige toujours une réponse — approbation ou refus — de la part de l’utilisateur qui autorise la demande, et les autorisations existantes ne sont pas vérifiées.

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

Si l’utilisateur refuse la demande envoyée par courriel, Auth0 renvoie à l’application cliente une réponse d’erreur semblable à 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 par courriel, Auth0 renvoie à l’application cliente un semblable à celui-ci :

{
    "access_token": "eyJh...",
    "id_token": "eyJh...",
    "expires_in": 86400,
    "scope": "openid",
    "token_type": "Bearer"
}

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

Quickstarts

Auth0 Overview

Configure Auth0

Applications

Notifications par courriel avec CIBA

Prérequis

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

Étape 2 : le tenant 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 : Auth0 envoie un lien à l’adresse courriel de l’utilisateur

Étape 5 : L’utilisateur s’authentifie dans le navigateur

Étape 6 : Le navigateur renvoie la réponse de l’utilisateur à Auth0

L’utilisateur accepte la requête d’authentification

L’utilisateur refuse la requête d’authentification

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

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

Pour en savoir plus

​Prérequis

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

​Étape 2 : le tenant 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 : Auth0 envoie un lien à l’adresse courriel de l’utilisateur

​Étape 5 : L’utilisateur s’authentifie dans le navigateur

​Étape 6 : Le navigateur renvoie la réponse de l’utilisateur à Auth0

​L’utilisateur accepte la requête d’authentification

​L’utilisateur refuse la requête d’authentification

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

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

​Pour en savoir plus

Prérequis

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

Étape 2 : le tenant 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 : Auth0 envoie un lien à l’adresse courriel de l’utilisateur

Étape 5 : L’utilisateur s’authentifie dans le navigateur

Étape 6 : Le navigateur renvoie la réponse de l’utilisateur à Auth0

L’utilisateur accepte la requête d’authentification

L’utilisateur refuse la requête d’authentification

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

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

Pour en savoir plus