Notifications par courriel avec CIBA

Découvrez comment authentifier les utilisateurs avec le flux Client-Initiated Backchannel Authentication à l’aide de notifications par courriel.

Pour utiliser les fonctionnalités de Client-Initiated Backchannel Authentication (CIBA), vous devez disposer d’un plan Enterprise 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 demande.

Lorsque vous utilisez des notifications par courriel avec CIBA, l’utilisateur se connecte sur l’appareil de consultation, 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 consultation, par exemple un téléviseur intelligent.

Le diagramme suivant illustre le flux CIBA de bout en bout avec notifications par courriel :

Les sections suivantes décrivent, étape par étape, le fonctionnement de l’authentification des utilisateurs avec CIBA à l’aide de notifications par courriel.

• Prérequis
• Étape 1 : L’application cliente lance une demande CIBA
• Étape 2 : Le locataire Auth0 confirme la réception de la demande CIBA
• Étape 3 : L’application cliente interroge le système 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 envoyer une demande CIBA par courriel avec Auth0, vous devez :

• Configurer l’authentification backchannel initiée par l’application pour votre locataire 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, définissez l’invite de consentement personnalisée.

​

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

Utilisez les API de recherche d’utilisateurs pour trouver l’utilisateur qui autorise la demande et pour lequel vous souhaitez lancer une requête CIBA, puis obtenir son ID utilisateur.

Une fois l’ID utilisateur de l’utilisateur autorisant obtenu, utilisez l’Authentication API ou nos SDKs pour envoyer une requête CIBA au point de terminaison /bc-authorize :

cURL

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}'

C#

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}"
                }
            }
        );

Go

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}",
  })

Java

//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 locataire. Il peut aussi s’agir d’un domaine personnalisé. Si le format iss_sub est utilisé, le nom du locataire est transmis dans la revendication iss.
client_id	Identifiant de l’application cliente.
client_secret	Méthode d’authentification de l’application utilisée pour authentifier l’utilisateur avec CIBA, comme 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 de l’utilisateur autorisant transmis dans la structure login_hint. Si le format iss_sub est utilisé, l’ID utilisateur est transmis dans la revendication sub. L’ID utilisateur peut avoir un format différent selon le fournisseur externe.
requested_expiry	Durée maximale, en secondes, pendant laquelle la session CIBA doit rester valide. L’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 expiration personnalisée pour le flux CIBA. Le paramètre requested_expiry aide à déterminer le canal de notification utilisé par CIBA : Si vous définissez requested_expiry à 300 secondes ou moins, CIBA utilise le canal de notification mobile push 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 (72 heures), 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 les caractères +-_.,:#.

Une limite de débit propre à l’utilisateur s’applique : l’utilisateur autorisant ne recevra pas plus de 5 requêtes par minute.

​

Étape 2 : le locataire Auth0 accuse réception de la demande CIBA

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

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

La valeur auth_req_id est transmise au point de terminaison /token pour vérifier périodiquement si le flux CIBA est terminé.

​

Étape 3 : L’application effectue des requêtes de sondage pour obtenir une réponse

Utilisez l’Authentication API ou nos SDKs 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();

Tant que l’utilisateur 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"
}

L’intervalle d’attente pour la scrutation est d’environ cinq secondes. Si vous effectuez la scrutation 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 résoudre 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

Le serveur d’autorisation Auth0 utilise login_hint, qui contient l’ID de l’utilisateur autorisant, pour lancer l’authentification de l’utilisateur sur l’appareil d’authentification :

• Le serveur d’autorisation Auth0 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 vers le point de terminaison /bc-verify, où le paramètre de requête consent fait référence à la requête CIBA en attente de consentement.

​

É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 identifiants fournis au paramètre login_hint envoyé au point de terminaison /bc-authorize lorsque l’application lance une requête CIBA. Sinon, un message d’erreur s’affiche et il doit se déconnecter, puis réessayer.

Comme dans un flux de connexion standard, le déclencheur post-login d’Actions s’exécute dans le flux CIBA par courriel, ce qui permet aux clients de fournir une logique personnalisée pour appliquer des stratégies 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 de 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 Login Trigger.

Une fois authentifié, le navigateur présente à l’utilisateur les détails de consentement provenant de l’API Consent d’Auth0, notamment binding_message, scope et audience. Les scopes sont filtrés en fonction de votre stratégie RBAC. Pour en savoir plus, consultez Role-Based Access Control.

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

{
  "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 demande d’authentification à ce stade-ci.

​

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

Le navigateur transmet la réponse de l’utilisateur à Auth0. Selon que l’utilisateur accepte ou refuse la demande d’authentification, Auth0 affiche les écrans Consent suivants, que vous devez personnaliser en configurant les invites Consent :

​

L’utilisateur accepte la demande d’authentification

​

L’utilisateur refuse la demande d’authentification

​

Étape 7 : Auth0 reçoit la réponse de l’utilisateur après la fin du flux

L’application termine la scrutation dès la réception d’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 qui autorise la demande, et les autorisations existantes ne sont pas vérifiées.

​

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

Si l’utilisateur refuse la demande d’accès au courriel, Auth0 renvoie à l’application cliente une réponse d’erreur semblable à la suivante :

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

Si l’utilisateur approuve la demande d’accès au courriel, Auth0 renvoie un jeton d’accès semblable à celui-ci à l’application cliente :

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

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

​

En savoir plus

• Flux d’authentification par canal arrière initié par l’application
• Configurer l’authentification par canal arrière initiée par l’application