Notifications poussées mobiles avec CIBA

Découvrez comment authentifier les utilisateurs avec le flux d’authentification par canal arrière initiée par le client à l’aide de notifications poussées mobiles.

Pour utiliser les fonctionnalités de Client-Initiated Backchannel Authentication (CIBA), vous devez disposer d’un forfait Enterprise ou d’une option appropriée. Consultez la tarification Auth0 pour en savoir plus.

Lorsque vous utilisez des notifications poussées mobiles avec CIBA, l’utilisateur reçoit une notification poussée pour s’authentifier ou autoriser une requête sur son appareil mobile inscrit. Vous pouvez envoyer des notifications poussées 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 poussées mobiles authentifie et autorise les utilisateurs sur leur appareil mobile, sans nécessiter de navigateur. Comme l’appareil de consommation n’exige 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 diagramme suivant illustre le flux CIBA de bout en bout avec notifications poussées mobiles :

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

• 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 pour obtenir une réponse
• Étape 4 : l’application mobile reçoit la notification poussée
• É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 renvoie le jeton d’accès à l’application cliente

​

Prérequis

Pour initier une requête CIBA avec notification push à l’aide d’Auth0, vous devez :

• Configurer l’authentification par canal arrière initiée par le client pour votre locataire et votre application, y compris les notifications poussées 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 initie une requête CIBA

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

Une fois que vous disposez de l’ID utilisateur de l’utilisateur qui doit autoriser la demande, utilisez l’Authentication API ou nos SDK pour envoyer une requête CIBA à l’endpoint /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 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 l’authentification de 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 la demande, transmis dans la structure login_hint. Si le format iss_sub est utilisé, l’ID utilisateur est transmis dans la revendication sub. Le format de l’ID utilisateur peut varier selon le fournisseur externe.
requested_expiry	Durée maximale, en secondes, pendant laquelle la session CIBA doit demeurer 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 quel canal de notification CIBA est utilisé : Si vous définissez requested_expiry à 300 secondes ou moins, CIBA utilise le canal de notification poussée mobile s’il est activé. Si MFA n’est pas configuré 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 lier 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 +-_.,:#.

Une limite de débit s’applique par utilisateur : l’utilisateur qui autorise la demande ne recevra pas plus de 5 requêtes par minute.

​

Étape 2 : le locataire Auth0 confirme la demande CIBA

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

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

La valeur auth_req_id est transmise au point de terminaison /token pour interroger l’état d’avancement du flux CIBA jusqu’à son terme.

​

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

Utilisez l’Authentication API ou nos SDKs pour appeler l’endpoint /token avec le type d’octroi urn:openid:params:grant-type:ciba et l’auth_req_id que vous avez reçu de l’endpoint /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 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 des scrutations trop fréquentes, vous recevrez la réponse suivante, dont 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 cette erreur, attendez le prochain intervalle (en secondes) avant d’interroger le point de terminaison /token.

​

Étape 4 : L’application mobile reçoit la notification poussée

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

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

Les exemples de code suivants montrent des implémentations de notifications poussées mobiles pour iOS et Android à l’aide du Guardian SDK :

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 poussées que vous pourriez utiliser... */
}

​

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

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

Si vous utilisez une application personnalisée, les exemples de code suivants montrent des implémentations iOS et Android qui récupèrent des données depuis l’API Auth0 Consent :

iOS

let device: AuthenticationDevice = // l’objet que vous avez obtenu pendant le processus initial d’inscription au SDK Guardian 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 du consentement à l’utilisateur
            case .failure(let cause):
                // un problème est survenu
        }
    }
}

Android

Enrollment enrollment = // l’objet que vous avez obtenu pendant le processus initial d’inscription au SDK Guardian 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 du 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’API Consent d’Auth0 renvoie à l’application Auth0 Guardian ou à votre application personnalisée intégrée au SDK Auth0 Guardian les détails du consentement, y compris binding_message, scope et audience. Les scopes renvoyés à l’application mobile sont filtrés selon votre stratégie 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 présente une réponse type 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
}

À cette étape, l’utilisateur peut accepter ou refuser la demande 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 SDK Auth0 Guardian, les exemples de code suivants présentent des implémentations iOS et Android qui traitent la réponse de l’utilisateur :

​

L’utilisateur accepte la demande 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 demande d’authentification a été refusée avec succès
        case .failure(let cause):
            // une erreur s’est produite; vérifiez la cause pour comprendre ce qui n’a pas fonctionné
        }
    }

Android

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

​

L’utilisateur refuse la demande 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 demande 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 à la scrutation 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 qui autorise la demande, et les octrois existants ne sont pas vérifiés.

​

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

 Si l’utilisateur refuse la demande de notification push, 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 de notification 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 le scope offline_access a été inclus dans la requête initiale vers /bc-authorize.

​

En savoir plus

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