Notificaciones push móviles con CIBA

Aprenda a autenticar usuarios con el flujo autenticación de canal secundario iniciada por el cliente mediante notificaciones push móviles.

Para usar las funciones de autenticación de canal secundario iniciada por el cliente (CIBA), debe tener un Enterprise Plan o un complemento adecuado. Consulte Auth0 Pricing para obtener más información.

Cuando usa notificaciones push móviles con CIBA, el usuario recibe una notificación push para autenticarse o autorizar una solicitud en su dispositivo móvil inscrito. Puede enviar notificaciones push móviles con CIBA mediante la aplicación Auth0 Guardian o una aplicación personalizada integrada con el SDK de Auth0 Guardian.

El flujo de CIBA con notificaciones push móviles autentica y autoriza a los usuarios en su dispositivo móvil, sin necesidad de usar un navegador. Como el dispositivo desde el que se inicia la solicitud no requiere una sesión activa en el navegador, el usuario no necesita haber iniciado sesión antes de que se desencadene una solicitud de CIBA. Esto también garantiza que el flujo de CIBA no afecte ninguna sesión existente que el usuario pueda tener.

El siguiente diagrama muestra el flujo completo de CIBA con notificaciones push móviles:

Las siguientes secciones explican paso a paso cómo funciona la autenticación de usuarios con CIBA mediante notificaciones push móviles.

• Requisitos previos
• Paso 1: La aplicación cliente inicia una solicitud de CIBA
• Paso 2: El Tenant de Auth0 confirma la solicitud de CIBA
• Paso 3: La aplicación cliente consulta si hay una respuesta
• Paso 4: La aplicación móvil recibe la notificación push
• Paso 5: La aplicación móvil recupera los detalles de consent
• Paso 6: La aplicación móvil presenta los detalles de consent al usuario
• Paso 7: La aplicación móvil envía la respuesta del usuario de vuelta a Auth0
• Paso 8: Auth0 recibe la respuesta del usuario una vez completado el flujo
• Paso 9: Auth0 devuelve el token de acceso a la aplicación cliente

​

Requisitos previos

Para iniciar una solicitud push de CIBA con Auth0, debe:

• Configurar la autenticación de canal secundario iniciada por el cliente para su Tenant y su aplicación, incluidas las notificaciones push móviles.
• Establecer el parámetro requested_expiry en un valor de 300 segundos o menos. Para obtener más información, consulte Configurar el canal de notificación.

​

Paso 1: La aplicación cliente inicia una solicitud de CIBA

Utiliza las API de búsqueda de usuarios para encontrar al usuario que autoriza para el que quieras iniciar una solicitud de CIBA y obtener su ID de usuario.

Una vez que tengas el ID de usuario del usuario que autoriza, usa la Authentication API o nuestros SDKs para enviar una solicitud de CIBA al 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

//Creación de una instancia de AuthClient
AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

//Autorización
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();

Parámetros	Descripción
tenant	Nombre del Tenant. También puede ser un dominio personalizado. Si se usa el formato iss_sub, el nombre del Tenant se pasa dentro del claim iss.
client_id	Identificador de la aplicación cliente.
client_secret	Método de autenticación del cliente que se usa para la autenticación del usuario con CIBA, como Secreto del cliente, Private Key JWT o autenticación mTLS. Si utiliza Private Key JWT o mTLS, no necesita incluir el secreto del cliente.
scope	Debe incluir openid. El scope puede incluir opcionalmente offline_access para solicitar un Token de actualización. Sin embargo, para la autorización puntual de una transacción con el flujo CIBA, no se necesita un token de actualización y no tiene ningún significado en este contexto.
user_id	ID del usuario que autoriza, que se pasa dentro de la estructura login_hint. Si se usa el formato iss_sub, el ID de usuario se pasa dentro del claim sub. El ID de usuario puede tener un formato distinto según el proveedor externo.
requested_expiry	La duración máxima, en segundos, durante la cual la sesión de CIBA debe ser válida. La expiración solicitada del flujo CIBA debe estar entre 1 y 259200 segundos (72 horas), y el valor predeterminado es 300 segundos. Incluya el parámetro requested_expiry para establecer una expiración personalizada para el flujo CIBA. El parámetro requested_expiry ayuda a determinar qué canal de notificación usa CIBA: Si establece requested_expiry en un valor de 300 segundos o menos, CIBA usa el canal de notificaciones push móviles si está habilitado. Si no ha configurado MFA para su Tenant, la solicitud de CIBA falla. Si establece requested_expiry en un valor entre 301 y 259200 segundos (72 horas), CIBA usa el canal de notificación por correo electrónico si está habilitado.
binding_message	Mensaje legible para humanos que se usa para vincular el flujo CIBA entre los dispositivos de autenticación y de consumo. El mensaje de vinculación es obligatorio y admite hasta 64 caracteres. Use solo caracteres alfanuméricos y +-_.,:#.

Hay un límite de tasa específico por usuario: no se enviarán más de 5 solicitudes por minuto al usuario que autoriza.

​

Paso 2: El Tenant de Auth0 confirma la solicitud de CIBA

Si el Tenant de Auth0 recibe correctamente la solicitud POST, deberías recibir una respuesta que contenga un auth-req-id que hace referencia a la solicitud:

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

El valor auth_req_id se pasa al endpoint /token para sondear la finalización del flujo CIBA.

​

Paso 3: La aplicación cliente consulta periódicamente si hay una respuesta

Utilice la Authentication API o nuestros SDKs para llamar al endpoint /token con el grant type urn:openid:params:grant-type:ciba y el auth_req_id que recibió del 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();

Hasta que el usuario que autoriza apruebe la transacción, debería recibir la siguiente respuesta:

{
    "error": "authorization_pending",
    "error_description": "La autorización del usuario final está pendiente"
}

Hay un intervalo de espera de aproximadamente cinco segundos entre cada sondeo. Si realiza el sondeo con demasiada frecuencia, recibirá la siguiente respuesta, donde la descripción varía según el intervalo de espera progresiva:

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

Para resolver el error, espere al siguiente intervalo (en segundos) antes de consultar el endpoint /token.

​

Paso 4: La aplicación móvil recibe la notificación push

Auth0 envía una notificación push a la aplicación móvil o al dispositivo registrado del usuario mediante la aplicación Auth0 Guardian o una aplicación personalizada integrada con el SDK de Auth0 Guardian.

Si utiliza una aplicación personalizada, el SDK de Auth0 Guardian proporciona métodos para analizar los datos recibidos de la notificación push y devolver una instancia de Notification lista para usar. La instancia de Notification incluye un identificador de vinculación de la transacción, o txlinkid, que la aplicación móvil usa para recuperar los detalles de consent desde Auth0.

Los siguientes ejemplos de código muestran implementaciones de notificaciones push móviles en iOS y Android con el SDK de Guardian:

iOS

//implementación 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) {
         // Implemente esta función para mostrar la pantalla y gestionar la aprobación o el rechazo del usuario.
         handleGuardianNotification(notification: notification)
    }
}

Android

// en el listener de FCM recibe un RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    if (notification != null) {
        // recibió una notificación de Guardian; gestiónela
        handleGuardianNotification(notification);
        return;
    }
    /* gestione otras notificaciones push que pueda estar usando ... */
}

​

Paso 5: La aplicación móvil recupera los detalles del consent

La aplicación Auth0 Guardian o una aplicación personalizada integrada con el SDK de Auth0 Guardian recupera los detalles del consent, es decir, el contenido de binding_message, de la Auth0 Consent API.

Si utiliza una aplicación personalizada, los siguientes ejemplos de código muestran implementaciones de ejemplo para iOS y Android que recuperan datos de la Auth0 Consent API:

iOS

let device: AuthenticationDevice = // el objeto que obtuvo durante el proceso inicial de inscripción con el SDK de Auth0 Guardian y almacenó localmente
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):
                // presentar al usuario los detalles del consent
            case .failure(let cause):
                // algo salió mal
        }
    }
}

Android

Enrollment enrollment = // el objeto que obtuvo durante el proceso inicial de inscripción con el SDK de Auth0 Guardian y almacenó localmente
if (notification.getTransactionLinkingId() != null) {
    guardian
      .fetchConsent(notification, enrollment)
      .start(new Callback<Enrollment> {
        @Override
        void onSuccess(RichConsent consentDetails) {
            // presentar al usuario los detalles del consent 
        }
        @Override
        void onFailure(Throwable exception) {
            // algo salió mal 
        }
      });
}

​

Paso 6: La aplicación móvil presenta al usuario los detalles del consent

La API de consent de Auth0 responde a la aplicación Auth0 Guardian o a tu aplicación personalizada integrada con el SDK de Auth0 Guardian con los detalles del consent, incluidos binding_message, scope y audience. Los alcances que se devuelven a la aplicación móvil se filtran según tu política de RBAC. Para obtener más información, consulta Control de acceso basado en roles.

La aplicación móvil presenta al usuario la solicitud de autenticación y/o los detalles del consent.

El siguiente ejemplo de código muestra una respuesta de ejemplo de la API de consent de 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
}

En este punto, el usuario puede aceptar o rechazar la solicitud de autenticación.

​

Paso 7: La aplicación móvil envía la respuesta del usuario a Auth0

La aplicación Auth0 Guardian o su aplicación personalizada envía la respuesta del usuario a Auth0.

Si utiliza una aplicación personalizada integrada con el SDK de Auth0 Guardian, los siguientes ejemplos de código muestran implementaciones para iOS y Android que gestionan la respuesta del usuario:

​

El usuario acepta la solicitud de autenticación

iOS

Guardian
    .authentication(forDomain: "{yourTenantDomain}", device: device)
    .allow(notification: notification)
    // o reject(notification: notification, withReason: "hacked")
    .start { result in
        switch result {
        case .success:
            // la solicitud de autenticación se rechazó correctamente
        case .failure(let cause):
            // se produjo un error; revisa cause para ver qué salió mal
        }
    }

Android

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

​

El usuario rechaza la solicitud de autenticación

iOS

Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // o reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // la solicitud de autenticación se rechazó correctamente
            case .failure(let cause):
                // se produjo un error; revisa cause para ver qué salió mal
            }
        }

Android

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

​

Paso 8: Auth0 recibe la respuesta del usuario cuando finaliza el flujo

La aplicación cliente completa el sondeo al recibir una respuesta del endpoint /token. Un flujo CIBA siempre requiere una respuesta —ya sea de aprobación o de rechazo— del usuario que autoriza, y no se verifican las autorizaciones existentes.

​

Paso 9: Auth0 devuelve el token de acceso a la aplicación cliente

 Si el usuario rechaza la solicitud push, Auth0 devuelve a la aplicación cliente una respuesta de error como la siguiente:

{
    "error": "access_denied",
    "error_description": "El usuario final denegó la solicitud de autorización o ha caducado"
}

Si el usuario aprueba la solicitud de push, Auth0 devuelve a la aplicación cliente un token de acceso como el siguiente:

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

refresh_token solo estará presente si se incluyó el scope offline_access en la solicitud inicial a /bc-authorize.

​

Más información

• Flujo de autenticación de canal secundario iniciado por el cliente
• Configurar la autenticación de canal secundario iniciada por el cliente