Configurar e implementar SSO de aplicaciones nativas a web

Aprenda a configurar sus aplicaciones para usar SSO de aplicaciones nativas a web.

​

Configurar el SSO de aplicaciones nativas a web

Para usar el inicio de sesión único (SSO) de aplicaciones nativas a web, configure su aplicación nativa y su aplicación web (Single Page App o Regular Web App) para crear y administrar sesiones con la Management API de Auth0.

Necesita un token de acceso para usar la Management API o Auth0 CLI.

Para configurar el SSO de aplicaciones nativas a web, debe crear y administrar session_transfer_tokens y configurar sus aplicaciones nativa y web.

El SSO de aplicaciones nativas a web es compatible con los siguientes SDKs: Auth0 Android SDK, Auth0 Swift SDK y Auth0 React Native SDK.

La compatibilidad con el SSO de aplicaciones nativas a web está disponible en las siguientes herramientas: Auth0 Deploy CLI. Auth0 Terraform Provider y Auth0 CLI.

El SSO de aplicaciones nativas a web es compatible con cualquier flujo de autenticación que devuelva un token de actualización, como Resource Owner Password Flow y Authorization Code Flow with Proof Key for Code Exchange.

​

Crear y gestionar tokens de transferencia de sesión

La primera llamada a la Management API permite a sus aplicaciones nativas y web:

• Crear y gestionar session_transfer_tokens
• Crear sesiones en un navegador web mediante cookies o un parámetro de URL
• Vincular la sesión al dispositivo de un usuario mediante una dirección IP o un ASN

Para las aplicaciones existentes, haga una llamada PATCH al endpoint Update a Client. Para crear una nueva aplicación, haga una llamada POST al endpoint Create a Client:

{
  "session_transfer": {
    "can_create_session_transfer_token": false,
    "allowed_authentication_methods": ["cookie", "query"],
    "enforce_device_binding": "ip", // también "none" o "asn",
    "allow_refresh_token": false,
    "enforce_cascade_revocation": true,
    "enforce_online_refresh_tokens": true
  }
}

​

Configurar aplicaciones nativas

Una vez autenticado el usuario, Auth0 devuelve un Token de acceso, un token de ID y, opcionalmente, un Token de actualización.

Puede configurar su aplicación nativa para intercambiar un token de actualización por un Session Transfer Token. Si su aplicación web no admite la inyección de cookies, su aplicación nativa también debe configurar la Login URI de su aplicación web para inyectar el Session Transfer Token como parámetro de URI.

• Actualice su aplicación nativa mediante el Auth0 Dashboard:

  1. Vaya a Dashboard > Applications:
  2. Seleccione o cree su aplicación.
  3. Seleccione la pestaña Settings.
  4. En Session Transfer, habilite Allow Native to Web SSO.
  5. Seleccione Require Cascade Revocation para revocar automáticamente la sesión de la aplicación web y los tokens asociados.
  6. Seleccione Save para actualizar su aplicación.

• Actualice su aplicación nativa con su Token de acceso de la Management API mediante el endpoint Update a Client:

• Actualiza tu aplicación nativa mediante Auth0 CLI:

​

Configurar aplicaciones web

Antes de habilitar Session Transfer Token, asegúrate de haber configurado el URI de inicio de sesión de la aplicación de tu aplicación web para que gestione parámetros adicionales. Para obtener más información sobre los URI, consulta Configuración de la aplicación.

• Actualiza tu aplicación web con Auth0 Dashboard:

  1. Ve a Dashboard > Applications:
  2. Selecciona o crea tu aplicación web.
  3. Selecciona la pestaña Settings.
  4. En Session Transfer, habilita Native to Web SSO Methods.
  5. Selecciona Cookie Authentication y Query Authentication.
  6. Habilita Device Binding Method y elige None, ASN Binding o IP Address Binding.
  7. Habilita Allow Refresh Token Requests para emitir nuevos tokens de actualización después de una transferencia de sesión.
  8. Selecciona Use online refresh tokens.
  9. Selecciona Save para actualizar tu aplicación web.

• Actualiza tu aplicación web con el token de acceso de Management API mediante el endpoint Update a Client:

• Actualiza tu aplicación web con la Auth0 CLI:

​

Implementar SSO de nativa a web

El SSO de nativa a web ofrece una experiencia de usuario fluida al pasar usuarios autenticados de su aplicación nativa a su aplicación web.

Para ello, su aplicación nativa debe intercambiar un Token de actualización por un token de transferencia de sesión y enviar el token de transferencia de sesión, mediante una URL o una cookie, a su aplicación web para autorizar la sesión.

• Si allow_refresh_token está deshabilitado en el cliente, pero la aplicación solicita offline_access, Auth0 no emitirá un refresh_token, aunque la autenticación seguirá funcionando.

• Si la rotación del Token de actualización está habilitada, Auth0 devuelve un nuevo refresh_token en la llamada de intercambio de tokens. El intercambio del Token de actualización debe realizarse justo antes de que su código abra la aplicación web.

​

En la aplicación nativa

​

Paso 1: Intercambia un Token de actualización por un token de transferencia de sesión

Usa el endpoint /token en tu aplicación nativa para intercambiar el token de actualización por un token de transferencia de sesión.

• Intercambia un token de actualización por un token de transferencia de sesión con los SDK de Swift, Android o React Native:

SDK de Swift

credentialsManager.ssoCredentials { result in
    switch result {
    case .success(let ssoCredentials):
        print("Obtained SSO credentials: \(ssoCredentials)")
    case .failure(let error):
        print("Failed with: \(error)")
    }
}

// O bien, con async/await

do {
    let ssoCredentials = try await credentialsManager.ssoCredentials()
    print("Obtained SSO credentials: \(ssoCredentials)")
} catch {
    print("Failed with: \(error)")
}

SDK de Android

secureCredentialsManager.getSsoCredentials(
    mapOf(),  // parámetros opcionales
    object : Callback<SSOCredentials, CredentialsManagerException> {
        override fun onSuccess(result: SSOCredentials) {
            // Usa result.sessionTransferToken para autenticar
            // al usuario en una sesión web de tu aplicación
        }

        override fun onFailure(error: CredentialsManagerException) {
            // Gestiona el error
        }
    }
)

SDK de React Native

// Uso de Hooks
import { useAuth0 } from 'react-native-auth0';

function MyComponent() {
  const { getSSOCredentials } = useAuth0();

  const openWebApp = async () => {
    try {
      const ssoCredentials = await getSSOCredentials();
      // Usa ssoCredentials.sessionTransferToken para autenticar
      // al usuario en una sesión web de tu aplicación
      console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);
    } catch (error) {
      console.error('Failed to get SSO credentials:', error);
    }
  };
}

// Uso de la clase Auth0
import Auth0 from 'react-native-auth0';

const auth0 = new Auth0({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
});

const ssoCredentials = await auth0.credentialsManager.getSSOCredentials();
console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);

• Intercambia un token de actualización por un token de transferencia de sesión mediante HTTP:

Estos ejemplos usan marcadores de posición para las variables dinámicas. Sustituya los marcadores de posición por su dominio de Auth0, client_id y un refresh_token existente.

El inquilino de Auth0 devuelve un session_transfer_token de un solo uso y de corta duración (con una vigencia de 1 minuto).

{
    "access_token": "{session_transfer_token}",
    "issued_token_type": "urn:auth0:params:oauth:token-type:session_transfer_token",
    "token_type": "N_A",
    "expires_in": 60
}

Si la rotación de tokens de actualización está habilitada, el intercambio también devolverá un Token de actualización.

Si solicitaste un ID Token durante la autenticación, esta llamada también devolverá un ID Token.

​

Paso 2: Envíe el token de transferencia de sesión a través de una URL o una cookie

Hay dos opciones para enviar el session_transfer_token a su aplicación web, según los allowed_authentication_methods configurados.

Opción 1: Envíe el session_transfer_token como una cookie

Si su aplicación web, que usa WebView o un navegador, admite la inyección de cookies, puede configurar su aplicación nativa para:

• Agregar el session_transfer_token a una cookie.
• Abrir la aplicación web mediante WebView o un navegador.
• Iniciar sesión en la aplicación web en su dominio de Auth0 o Dominio personalizado. Como el session_transfer_token está incluido en la cookie, no se solicita al usuario la autenticación del primer factor.

Opción 2: Enviar session_transfer_token como parámetro de URL

Si su aplicación web no admite la inyección de cookies, puede configurar su aplicación nativa mediante parámetros de URL para:

• Agregar session_transfer_token como parámetro de URL.
• Abrir la aplicación web mediante WebView o el navegador.
• Iniciar sesión en la aplicación web agregando session_transfer_token como parámetro de URL al endpoint /authorize. El inquilino de Auth0 autentica al usuario sin requerir autenticación del primer factor, ya que session_transfer_token es válido y confiable.

​

En tu aplicación web

Cuando el token de transferencia de sesión se envía como una cookie, no se requiere ninguna configuración adicional, ya que el navegador envía la cookie en la solicitud al endpoint /authorize.

Implementa el SSO web único entre nativo y web en tu aplicación web mediante parámetros de URL:

​

Opción 1: Agregue el Session Transfer Token a la solicitud de su aplicación web

Desde la URL de inicio de sesión de la aplicación, redirija al endpoint /authorize cuando session_transfer_token se envíe como parámetro de URL.

​

Opción 2: Añada el Session Transfer Token a aplicaciones web que usan los SDK de Auth0

Los SDK de Auth0 no admiten automáticamente el SSO único de aplicaciones nativas a web y no incluyen session_transfer_token en la solicitud al endpoint /authorize.

A continuación, se muestran ejemplos de aplicaciones web que usan los SDK de Auth0 para redirigir session_transfer_token en la solicitud al endpoint /authorize:

Node (Express.js)

Si su aplicación web usa Express.js o el SDK de Auth0 para Express, puede usar el siguiente código para añadir compatibilidad de middleware para session_transfer_token.

javascript

const baseConfig = {
  authRequired: false,
  auth0Logout: true
};

// Extender el middleware para detectar automáticamente session_transfer_token
app.use((req, res, next) => {
  const { session_transfer_token } = req.query;

  // Crear una nueva configuración para cada solicitud y evitar la filtración de estado
  const config = { ...baseConfig };

  if (session_transfer_token) {
    config.authorizationParams = {
      session_transfer_token,
    };
  }

  auth(config)(req, res, next);
});

Auth0 SPA SDK (@auth0/auth0-spa-js)

Si tu aplicación web utiliza el Auth0 SPA SDK, puedes pasar session_transfer_token a loginWithRedirect() mediante authorizationParams.

typescript

import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
});

// Obtener session_transfer_token de los parámetros de consulta de la URL (enviado desde la app nativa)
const urlParams = new URLSearchParams(window.location.search);
const sessionTransferToken = urlParams.get('session_transfer_token');

// Usar loginWithRedirect con el session_transfer_token
if (sessionTransferToken) {
  await auth0.loginWithRedirect({
    authorizationParams: {
      session_transfer_token: sessionTransferToken,
      redirect_uri: window.location.origin,
    },
  });
}

SDK de React de Auth0 (@auth0/auth0-react)

Si tu aplicación web usa el SDK de React de Auth0, puedes usar loginWithRedirect del hook useAuth0 para pasar el session_transfer_token.

typescript

import { useEffect } from 'react';
import { useAuth0 } from '@auth0/auth0-react';

function App() {
  const { loginWithRedirect, isAuthenticated, isLoading } = useAuth0();

  useEffect(() => {
    if (isLoading || isAuthenticated) return;

    const urlParams = new URLSearchParams(window.location.search);
    const sessionTransferToken = urlParams.get('session_transfer_token');

    if (sessionTransferToken) {
      loginWithRedirect({
        authorizationParams: {
          session_transfer_token: sessionTransferToken,
        },
      });
    }
  }, [loginWithRedirect, isLoading, isAuthenticated]);

  return <div>...</div>;
}

SAML y WS-Federation

Si su aplicación web usa SAML o WS-Fed como proveedor de servicios y Auth0 como IdP, puede enviar session_transfer_token como parámetro de URL al endpoint /authorize de Auth0, y redirect_uri será la URL de inicio de sesión de SAML o WS-Fed.

​

SSO de nativo a web con Organizaciones

El SSO de nativo a web admite Organizaciones. Cuando un usuario se autentica con una organización en su aplicación nativa, el token de transferencia de sesión incluye el contexto de la organización.

Al usar Organizaciones con SSO de nativo a web, el parámetro organization en la solicitud /authorize de la aplicación web debe coincidir con la organización asociada al token de transferencia de sesión. Si no coincide, la autenticación fallará y se le pedirá al usuario que vuelva a iniciar sesión.

Para usar Organizaciones con SSO de nativo a web:

1. Autentique al usuario en su aplicación nativa con una organización:

javascript

// Inicio de sesión en la app nativa con organización
await authorize({
  organization: 'org_abc123',
  scope: 'openid profile email offline_access'
});

2. Al redirigir a la aplicación web, incluye la misma organización en la solicitud de /authorize:

bash

https://{yourDomain}/authorize?
  client_id={yourWebClientId}&
  redirect_uri={yourRedirectUri}&
  response_type=code&
  organization=org_abc123&
  session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN

Si la organización de la solicitud /authorize no coincide con la organización del token de transferencia de sesión, el token de transferencia de sesión se rechaza y el usuario es redirigido a la página de inicio de sesión para volver a autenticarse. Se genera una entrada de advertencia en los registros de su inquilino con la descripción del evento “Single Sign-On failed: Session Transfer Token organization mismatch detected.”

​

Token de transferencia de sesión con Actions

El uso de session_transfer_token con Actions le permite configurar capacidades de detección y respuesta ante riesgos posteriores a la autenticación para reforzar la protección del usuario.

Para ello, el objeto post-login de Action event.session_transfer_token proporciona información relevante, incluido el client_id único, scope e información de request, como ip, asn y user_agent, así como información de geoip, como cityName, countryCode, entre otros. Para obtener más información, consulte Actions Triggers: post-login - Event Object.

El siguiente código de Action le permite rechazar dinámicamente una transacción en función de la información de geolocalización:

javascript

/**
* Controlador que se invocará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para modificar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
   if(
     event.session_transfer_token &&
     event.session_transfer_token.request.geoip.countryCode !== event.request.geoip.countryCode
     ) {
     api.access.deny("Network mismatch detected")
   }
};

​

Acceder a los metadatos del token de actualización padre

El SSO de nativo a web le permite acceder a los metadatos del token de actualización padre que se utilizó para iniciar el flujo de SSO. Esto le permite pasar información contextual recopilada en la aplicación nativa (como la integridad del dispositivo, señales de riesgo o contexto personalizado) a la sesión web creada a partir del session_transfer_token.

Auth0 expone esta información en las Actions de Post Login mediante el objeto event.session.session_transfer.parent_refresh_token.metadata. Esto permite la propagación segura y estandarizada de metadatos entre plataformas.

Caso de uso de ejemplo: Una aplicación móvil recopila datos de riesgo (puntuación del dispositivo, ubicación, etc.) y los almacena en los metadatos del token de actualización. Cuando la aplicación nativa inicia un flujo de SSO de nativo a web, esos metadatos pasan a estar disponibles automáticamente en la sesión web correspondiente mediante Actions.

El siguiente código de Action le permite aplicar lógica de acceso condicional basada en metadatos de confianza del dispositivo procedentes de la aplicación nativa:

javascript

/**
* Controlador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para modificar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Acceder a los metadatos del Token de actualización principal (aplicación nativa)
  const parentMetadata = event.session?.session_transfer?.parent_refresh_token?.metadata;

  if (parentMetadata) {
    const deviceTrustLevel = parentMetadata.device_trust;

    if (deviceTrustLevel !== 'high') {
      api.access.deny("Device trust level insufficient.");
    }

    // También puede agregar claims según el contexto de la aplicación nativa
    if (parentMetadata.subscription_tier) {
      api.idToken.setCustomClaim('subscription_tier', parentMetadata.subscription_tier);
    }
  }
};

​

Monitoreo

Puede monitorear la actividad de SSO de Native to Web revisando los registros del Tenant.

​

Registros de intercambio de tokens

• sertft : Intercambio correcto del Token de actualización. Este registro corresponderá a un intercambio de SSO de una aplicación nativa a una aplicación web cuando el campo audience sea "audience":"urn:$auth0Domain:session_transfer"
• fertft: Intercambio fallido del Token de actualización. Este registro corresponderá a un intercambio de SSO de una aplicación nativa a una aplicación web cuando el campo audience sea "audience": "urn:$auth0Domain:session_transfer"

​

Registros de advertencia de validación de la transferencia de sesión

Auth0 emite registros de advertencia (w) cuando falla la validación del token de transferencia de sesión durante la solicitud /authorize. Estos registros te ayudan a solucionar problemas de SSO de nativo a web:

Descripción del evento	Causa
Single Sign-On failed: Session Transfer Token not found or expired. This may indicate token reuse or expiration.	No se encontró el token de transferencia de sesión, ya se usó o expiró (los tokens son de un solo uso y expiran al cabo de 1 minuto).
Single Sign-On failed: Session Transfer Token device binding validation failed due to IP/ASN mismatch.	La dirección IP o el ASN de la solicitud web no coinciden con la vinculación del dispositivo configurada para el token de transferencia de sesión.
Single Sign-On failed: Session Transfer Token organization mismatch detected.	El parámetro organization de la solicitud /authorize no coincide con la organización del token de transferencia de sesión.
Single Sign-On failed: Session Transfer Token user mismatch detected.	Una sesión de Auth0 ya existente pertenece a un usuario distinto del token de transferencia de sesión.
Single Sign-On failed: Parent refresh token not found. Session Transfer Token won't be used for session establishment.	El token de actualización principal usado para crear el token de transferencia de sesión fue revocado o eliminado.