Notifications push mobiles avec CIBA

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

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 en savoir plus.

Lorsque vous utilisez des notifications push mobiles avec CIBA, l’utilisateur reçoit une notification push pour s’authentifier ou autoriser une requête sur son appareil mobile enregistré. Vous pouvez envoyer des notifications push mobiles avec CIBA à l’aide de l’application Auth0 Guardian ou d’une application personnalisée intégrée au SDK Auth0 Guardian.

Le flux CIBA avec notifications push mobiles authentifie et autorise les utilisateurs sur leur appareil mobile, sans nécessiter de navigateur. Comme l’appareil de consommation ne nécessite pas de session de navigateur active, l’utilisateur n’a pas besoin d’être connecté avant qu’une requête CIBA soit déclenchée. Cela garantit également que le flux CIBA n’aura aucune incidence sur les sessions existantes de l’utilisateur.

Le schéma suivant illustre le flux CIBA de bout en bout avec notifications push mobiles :

Les sections suivantes expliquent étape par étape le fonctionnement de l’authentification des utilisateurs avec CIBA à l’aide de notifications push mobiles.

• 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’application mobile reçoit la notification push
• Étape 5 : L’application mobile récupère les détails du consentement
• Étape 6 : L’application mobile présente les détails du consentement à l’utilisateur
• Étape 7 : L’application mobile 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 retourne le jeton d’accès à l’application cliente

​

Prérequis

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

• Configure Client-Initiated Backchannel Authentication pour votre tenant et votre application, y compris les notifications push mobiles.
• Définir le paramètre requested_expiry sur une valeur de 300 secondes ou moins. Pour en savoir plus, consultez Configurer le canal de notification.

​

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

Utilisez les API User Search pour trouver l’utilisateur qui autorise la demande 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 demande, 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 = "openid",
                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 tenant. Il peut aussi s’agir d’un custom domain. Si le format iss_sub est utilisé, le nom du tenant est transmis dans la claim iss.
client_id	Identifiant de la client application.
client_secret	Méthode de client authentication utilisée pour la user authentication avec CIBA, comme Client Secret, Private Key JWT ou mTLS authentication. 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	user ID de l’authorizing user transmis dans la structure login_hint. Si le format iss_sub est utilisé, le user ID est transmis dans la claim sub. Le user ID peut avoir un format différent selon l’external provider.
requested_expiry	La durée maximale, en secondes, pendant laquelle la session CIBA doit rester valide. La durée d’expiration demandée du CIBA flow peut aller de 1 à 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 permet aussi de déterminer quel canal de notification CIBA utilise : Si vous définissez requested_expiry à 300 secondes ou moins, CIBA utilise le canal de mobile push notification s’il est activé. Si vous n’avez pas configuré MFA 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 email notification s’il est activé.
binding_message	Message human-readable utilisé pour relier le CIBA flow entre les appareils d’authentication et de consommation. Le message de liaison est obligatoire et ne peut pas dépasser 64 caractères. Utilisez uniquement des caractères alphanumériques et +-_.,:#.

Il existe une rate limit propre à l’utilisateur : l’authorizing user 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 à cette requête :

{
    "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 cliente interroge périodiquement pour obtenir une réponse

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

cURL

curl --location 'https://$tenant.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<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 = "<CLIENT_ID>",
                ClientSecret = "<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 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 intervalle d’attente d’environ cinq secondes pour le polling. Si vous effectuez le polling trop fréquemment, vous recevrez la réponse suivante, où la description varie selon l’intervalle de temporisation exponentielle :

{
"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 : L’application mobile reçoit la notification push

Auth0 envoie une notification push à l’application mobile enregistrée de l’utilisateur ou à son appareil par l’entremise de l’application Auth0 Guardian ou d’une application personnalisée intégrée au Auth0 Guardian SDK.

Si vous utilisez une application personnalisée, le Auth0 Guardian SDK fournit des méthodes pour analyser les données reçues dans la notification push et renvoyer une instance Notification prête à l’emploi. L’instance Notification comprend un ID de liaison de transaction, ou txlinkid, que l’application mobile utilise pour récupérer les détails du consentement depuis Auth0.

Les exemples de code suivants montrent des mises en œuvre de notifications push mobiles pour iOS et Android à l’aide du SDK Guardian :

iOS

//implémentation de UNUserNotificationCenterDelegate
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo
    if let notification = Guardian.notification(from: userInfo) {
         // Implémentez cette fonction pour afficher l’invite et gérer le consentement ou le refus de l’utilisateur.
         handleGuardianNotification(notification: notification)
    }
}

Android

// dans l’écouteur FCM, vous recevez un RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    if (notification != null) {
        // vous avez reçu une notification Guardian, traitez-la
        handleGuardianNotification(notification);
        return;
    }
    /* traitez les autres notifications push que vous pourriez utiliser ... */
}

​

Étape 5 : L’application mobile récupère les détails de consentement

Votre application Auth0 Guardian ou votre application personnalisée intégrée à l’Auth0 Guardian SDK récupère les détails de consentement, c.-à-d. le contenu de binding_message, auprès de l’Auth0 Consent API.

Si vous utilisez une application personnalisée, les exemples de code suivants montrent des mises en œuvre iOS et Android qui récupèrent des données auprès de l’Auth0 Consent API :

iOS

let device: AuthenticationDevice = // l’objet que vous avez obtenu pendant le processus d’enrôlement initial de l’Auth0 Guardian SDK et stocké localement
if let consentId = notification.transactionLinkingId {
    Guardian
        .consent(forDomain: {yourTenantDomain}, device: device)
        .fetch(consentId: consentId, notificationToken: notification.transactionToken)
        .start{result in
            switch result {
            case .success(let payload):
                // présenter les détails de consentement à l’utilisateur
            case .failure(let cause):
                // un problème est survenu
        }
    }
}

Android

Enrollment enrollment = // l’objet que vous avez obtenu pendant le processus d’enrôlement initial de l’Auth0 Guardian SDK et stocké localement
if (notification.getTransactionLinkingId() != null) {
    guardian
      .fetchConsent(notification, enrollment)
      .start(new Callback<Enrollment> {
        @Override
        void onSuccess(RichConsent consentDetails) {
            // présenter les détails de consentement à l’utilisateur 
        }
        @Override
        void onFailure(Throwable exception) {
            // un problème est survenu 
        }
      });
}

​

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

L’Auth0 Consent API répond à l’application Auth0 Guardian ou à votre application personnalisée intégrée à l’Auth0 Guardian SDK avec les détails du consentement, y compris binding_message, scope et audience. 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’application mobile présente à l’utilisateur la demande d’authentification et/ou les détails du consentement.

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 alors accepter ou refuser la requête d’authentification.

​

Étape 7 : L’application mobile renvoie la réponse de l’utilisateur à Auth0

L’application Auth0 Guardian ou votre application personnalisée renvoie la réponse de l’utilisateur à Auth0.

Si vous utilisez une application personnalisée intégrée au Auth0 Guardian SDK, les exemples de code suivants présentent des mises en œuvre pour iOS et Android qui traitent la réponse de l’utilisateur :

​

L’utilisateur accepte la requête d’authentification

iOS

Guardian
    .authentication(forDomain: "{yourTenantDomain}", device: device)
    .allow(notification: notification)
    // ou reject(notification: notification, withReason: "hacked")
    .start { result in
        switch result {
        case .success:
            // la requête d’authentification a été rejetée avec succès
        case .failure(let cause):
            // une erreur s’est produite; vérifiez cause pour voir ce qui n’a pas fonctionné
        }
    }

Android

guardian
    .allow(notification, enrollment)
    .execute(); // ou start(new Callback<> ...)

​

L’utilisateur refuse la requête d’authentification

iOS

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // ou reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // la requête d’authentification a bien été refusée
            case .failure(let cause):
                // une erreur s’est produite; vérifiez la cause pour comprendre ce qui n’a pas fonctionné
            }
        }

Android

guardian
    .reject(notification, enrollment) // ou reject(notification, enrollment, reason)
    .execute(); // ou start(new Callback<> ...)

​

É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 de l’utilisateur autorisant, qu’il s’agisse d’une approbation ou d’un refus, et les autorisations déjà accordées ne sont pas vérifiées.

​

É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 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 push, Auth0 renvoie à l’application cliente un jeton d’accès comme 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 /bc-authorize.

​

En savoir plus

• Client-Initiated Backchannel Authentication Flow
• Configurer Client-Initiated Backchannel Authentication