Configurer et Implement Native to Web SSO

Découvrez comment configurer vos applications pour utiliser l’authentification unique Native to Web.

​

Configurer Native to Web SSO

Pour utiliser Native to Web authentification unique (SSO), configurez vos applications natives et Web (Single Page App ou application Web traditionnelle) pour créer et gérer des sessions avec la Management API d’Auth0.

Il vous faut un jeton d’accès pour utiliser la Management API ou Auth0 CLI.

Pour configurer Native to Web SSO, vous devez créer et gérer des session_transfer_tokens, puis configurer vos applications natives et Web.

Native to Web SSO prend en charge les SDK suivants : Auth0 Android SDK, Auth0 Swift SDK et Auth0 React Native SDK.

La prise en charge de Native to Web SSO est offerte dans les outils suivants : Auth0 Deploy CLI, Auth0 Terraform Provider et Auth0 CLI.

Native to Web SSO prend en charge tout flux d’authentification qui renvoie un jeton d’actualisation, comme le flux de mot de passe du propriétaire de la ressource et le flux de code d’autorisation avec clé de preuve pour l’échange de code.

​

Créer et gérer des jetons de transfert de session

Le premier appel à la Management API permet à vos applications natives et web de :

• Créer et gérer des session_transfer_tokens
• Créer des sessions dans un navigateur web à l’aide de cookies ou d’un paramètre d’URL
• Associer la session à l’appareil d’un utilisateur au moyen d’une adresse IP ou d’un ASN

Pour les applications existantes, faites une requête PATCH au point de terminaison Update a Client. Pour créer une nouvelle application, faites une requête POST au point de terminaison Create a Client :

{
  "session_transfer": {
    "can_create_session_transfer_token": false,
    "allowed_authentication_methods": ["cookie", "query"],
    "enforce_device_binding": "ip", // aussi "none" ou "asn",
    "allow_refresh_token": false,
    "enforce_cascade_revocation": true,
    "enforce_online_refresh_tokens": true
  }
}

​

Configurer les applications natives

Une fois l’utilisateur authentifié, Auth0 renvoie un jeton d’accès, un jeton ID et, facultativement, un jeton d’actualisation.

Vous pouvez configurer votre application native pour échanger un jeton d’actualisation contre un jeton de transfert de session. Si votre application web ne prend pas en charge l’injection de cookie, votre application native doit aussi configurer l’URI de connexion de votre application web afin d’injecter le jeton de transfert de session en tant que paramètre d’URI.

• Mettez à jour votre application native à l’aide du Auth0 Dashboard :

  1. Accédez à Dashboard > Applications:
  2. Sélectionnez ou créez votre application.
  3. Sélectionnez l’onglet Settings.
  4. Sous Session Transfer, activez Allow Native to Web SSO.
  5. Sélectionnez Require Cascade Revocation pour révoquer automatiquement la session de l’application web et les jetons associés.
  6. Sélectionnez Save pour mettre à jour votre application.

• Mettez à jour votre application native à l’aide de votre jeton d’accès pour la Management API avec le point de terminaison Update a Client :

• Mettez à jour votre application native à l’aide d’Auth0 CLI :

​

Configurer les applications Web

Avant d’activer le jeton de transfert de session, assurez-vous d’avoir configuré l’Application Login URI de votre application Web pour prendre en charge des paramètres supplémentaires. Pour en savoir plus sur les URI, consultez Application Settings.

• Mettez à jour votre application Web dans l’Auth0 Dashboard :

  1. Accédez à Dashboard > Applications :
  2. Sélectionnez ou créez votre application Web.
  3. Sélectionnez l’onglet Settings.
  4. Sous Session Transfer, activez Native to Web SSO Methods.
  5. Sélectionnez Cookie Authentication et Query Authentication.
  6. Activez Device Binding Method : None, ASN Binding ou IP Address Binding.
  7. Activez Allow Refresh Token Requests pour émettre de nouveaux jetons d’actualisation après un transfert de session.
  8. Sélectionnez Use online refresh tokens.
  9. Sélectionnez Save pour mettre à jour votre application Web.

• Mettez à jour votre application Web à l’aide du jeton d’accès de la Management API avec le point de terminaison Update a Client :

• Mettez à jour votre application web à l’aide d’Auth0 CLI:

​

Implement Native to Web SSO

Native to Web Single SSO offre une expérience utilisateur fluide en permettant de faire passer des utilisateurs authentifiés de votre application native à votre application Web.

Pour ce faire, votre application native doit échanger un jeton d’actualisation contre un jeton de transfert de session et transmettre ce jeton de transfert de session, au moyen d’une URL ou d’un cookie, à votre application Web afin d’autoriser la session.

• Si allow_refresh_token est désactivé dans le client, mais que l’application demande offline_access, Auth0 n’émet pas de refresh_token, mais l’authentification continue de fonctionner.

• Si la rotation des jetons d’actualisation est activée, Auth0 renvoie un nouveau refresh_token dans la requête d’échange de jeton. L’échange du jeton d’actualisation doit avoir lieu juste avant que votre code n’ouvre l’application Web.

​

Dans votre application native

​

Étape 1 : Échanger un jeton d’actualisation contre un jeton de transfert de session

Utilisez le point de terminaison /token avec votre application native pour échanger le jeton d’actualisation contre un jeton de transfert de session.

• Échangez un jeton d’actualisation contre un jeton de transfert de session à l’aide du SDK Swift, du SDK Android ou du SDK React Native :

SDK Swift

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

// Ou, avec async/await

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

SDK Android

secureCredentialsManager.getSsoCredentials(
    mapOf(),  // paramètres facultatifs
    object : Callback<SSOCredentials, CredentialsManagerException> {
        override fun onSuccess(result: SSOCredentials) {
            // Utilisez result.sessionTransferToken pour authentifier
            // l'utilisateur dans une session Web de votre application
        }

        override fun onFailure(error: CredentialsManagerException) {
            // Gérez l'erreur
        }
    }
)

SDK React Native

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

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

  const openWebApp = async () => {
    try {
      const ssoCredentials = await getSSOCredentials();
      // Utilisez ssoCredentials.sessionTransferToken pour authentifier
      // l'utilisateur dans une session Web de votre application
      console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);
    } catch (error) {
      console.error('Failed to get SSO credentials:', error);
    }
  };
}

// Avec la classe 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);

• Échangez un jeton d’actualisation contre un jeton de transfert de session à l’aide de HTTP :

Ces exemples utilisent des valeurs de remplacement pour les variables dynamiques. Remplacez-les par votre domaine Auth0, votre client_id et un refresh_token existant.

Le tenant Auth0 renvoie un session_transfer_token à usage unique et de courte durée (durée de vie de 1 minute).

{
    "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 rotation des jetons d’actualisation est activée, l’échange renverra également un jeton d’actualisation.

Si vous avez demandé un ID Token lors de l’authentification, cette requête renverra également un ID Token.

​

Étape 2 : Envoyer le jeton de transfert de session au moyen d’une URL ou d’un cookie

Il existe deux façons d’envoyer le  session_transfer_token à votre application web, selon les allowed_authentication_methods configurées.

Option 1 : Envoyer le session_transfer_token dans un cookie

Si votre application web qui utilise WebView ou un navigateur prend en charge l’injection de cookie, vous pouvez configurer votre application native pour :

• Ajouter le session_transfer_token dans un cookie.
• Ouvrir l’application web à l’aide de WebView ou d’un navigateur.
• Connecter l’application web à votre tenant Auth0 ou à votre Domaine personnalisé. Comme le session_transfer_token est inclus dans le cookie, l’utilisateur n’a pas à effectuer l’authentification du premier facteur.

Option 2 : Envoyer le session_transfer_token comme paramètre d’URL

Si votre application web ne prend pas en charge l’injection de cookie, vous pouvez configurer votre application native à l’aide de paramètres d’URL pour :

• Ajouter le session_transfer_token comme paramètre d’URL.
• Ouvrir l’application web dans WebView ou dans un navigateur.
• Ouvrir une session dans l’application web en ajoutant le session_transfer_token comme paramètre d’URL au point de terminaison /authorize. Le tenant Auth0 authentifie l’utilisateur sans exiger d’authentification de premier facteur, puisque le session_transfer_token est valide et approuvé.

​

Dans votre application web

Lorsque le jeton de transfert de session est envoyé sous forme de cookie, aucune configuration supplémentaire n’est nécessaire, puisque le navigateur envoie le cookie dans la requête à l’endpoint /authorize.

Implémentez le SSO Web unique Native to Web dans votre application web à l’aide de paramètres d’URL :

​

Option 1 : Ajouter le jeton de transfert de session à la requête de votre application web

Depuis l’URL de connexion de l’application, redirigez vers le point de terminaison /authorize lorsque le session_transfer_token est envoyé en tant que paramètre d’URL.

​

Option 2 : Ajouter le jeton de transfert de session aux applications Web à l’aide des Auth0 SDKs

Les Auth0 SDKs ne prennent pas automatiquement en charge Native to Web Single SSO et n’incluent pas le session_transfer_token dans la requête du point de terminaison /authorize.

Vous trouverez ci-dessous des exemples d’applications Web utilisant les Auth0 SDKs pour rediriger le session_transfer_token dans la requête du point de terminaison /authorize :

Node (Express.js)

Si votre application web utilise Express.js ou le SDK Auth0 Express, vous pouvez utiliser le code ci-dessous pour ajouter la prise en charge de session_transfer_token dans le middleware.

javascript

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

// Extension du middleware pour détecter automatiquement session_transfer_token
app.use((req, res, next) => {
  const { session_transfer_token } = req.query;

  // Créer une nouvelle configuration pour chaque requête afin d'éviter les fuites d'état
  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 votre application Web utilise le Auth0 SPA SDK, vous pouvez transmettre le session_transfer_token à loginWithRedirect() au moyen de authorizationParams.

typescript

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

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

// Récupérer le session_transfer_token depuis les paramètres de requête URL (transmis depuis l'application native)
const urlParams = new URLSearchParams(window.location.search);
const sessionTransferToken = urlParams.get('session_transfer_token');

// Utiliser loginWithRedirect avec le session_transfer_token
if (sessionTransferToken) {
  await auth0.loginWithRedirect({
    authorizationParams: {
      session_transfer_token: sessionTransferToken,
      redirect_uri: window.location.origin,
    },
  });
}

Auth0 React SDK (@auth0/auth0-react)

Si votre application web utilise le Auth0 React SDK, vous pouvez utiliser loginWithRedirect à partir du hook useAuth0 pour transmettre le 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 et WS-Federation

Si votre application web utilise un fournisseur de services SAML ou WS-Fed et Auth0 comme IdP, vous pouvez transmettre le session_transfer_token en tant que paramètre d’URL au point de terminaison /authorize d’Auth0, et le redirect_uri est l’URL de connexion SAML ou WS-Fed.

​

Native to Web SSO avec Organizations

Native to Web SSO prend en charge Organizations. Lorsqu’un utilisateur s’authentifie auprès d’une organisation dans votre application native, le jeton de transfert de session inclut le contexte de l’organisation.

Lorsque vous utilisez Organizations avec Native to Web SSO, le paramètre organization dans la requête /authorize de l’application web doit correspondre à l’organisation associée au jeton de transfert de session. En cas d’incompatibilité, l’authentification échouera et l’utilisateur devra se connecter à nouveau.

Pour utiliser Organizations avec Native to Web SSO :

1. Authentifiez l’utilisateur dans votre application native avec une organisation :

javascript

// Connexion à l'application native avec une organisation
await authorize({
  organization: 'org_abc123',
  scope: 'openid profile email offline_access'
});

2. Lors de la redirection vers l’application web, incluez la même organisation dans la requête /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 l’organisation indiquée dans la requête /authorize ne correspond pas à celle du jeton de transfert de session, le jeton de transfert de session est rejeté et l’utilisateur est redirigé vers la page de connexion pour s’authentifier de nouveau. Une entrée d’avertissement est consignée dans les journaux du locataire avec la description d’événement “Échec de l’authentification unique : incompatibilité d’organisation détectée dans le jeton de transfert de session.”

​

Session Transfer Token avec Actions

L’utilisation de session_transfer_token avec Actions vous permet de configurer des capacités de détection et de réponse aux risques après l’authentification afin de mieux protéger les utilisateurs.

À cette fin, l’objet event.session_transfer_token de l’Action post-login fournit des renseignements pertinents, notamment le client_id unique, le scope, des informations sur la request, comme ip, asn, user_agent, ainsi que des informations geoip, comme cityName et countryCode, entre autres. Pour en savoir plus, consultez Actions Triggers: post-login - Event Object.

Le code d’Action ci-dessous vous permet de refuser dynamiquement une transaction en fonction des données de géolocalisation :

javascript

/**
* Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
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")
   }
};

​

Accéder aux métadonnées du jeton d’actualisation parent

Native to Web SSO vous permet d’accéder aux métadonnées du jeton d’actualisation parent utilisé pour lancer le flux SSO. Vous pouvez ainsi transmettre des informations contextuelles recueillies dans l’application native (comme l’intégrité de l’appareil, des signaux de risque ou un contexte personnalisé) à la session Web créée à partir du session_transfer_token.

Auth0 expose ces informations dans les Actions Post Login au moyen de l’objet event.session.session_transfer.parent_refresh_token.metadata. Cela permet une propagation sécurisée et normalisée des métadonnées entre les plateformes.

Exemple de cas d’utilisation : Une application mobile recueille des données de risque (score de l’appareil, emplacement, etc.) et les stocke dans les métadonnées du jeton d’actualisation. Lorsque l’application native lance un flux Native to Web SSO, ces métadonnées sont automatiquement accessibles dans la session Web correspondante via les Actions.

Le code de l’Action ci-dessous vous permet d’exécuter une logique d’accès conditionnel fondée sur les métadonnées de confiance de l’appareil provenant de l’application native :

javascript

/**
* Handler qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Accéder aux métadonnées du refresh token parent (application native)
  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.");
    }

    // Vous pouvez également ajouter des claims selon le contexte de l'application native
    if (parentMetadata.subscription_tier) {
      api.idToken.setCustomClaim('subscription_tier', parentMetadata.subscription_tier);
    }
  }
};

​

Surveillance

Vous pouvez surveiller l’activité Native to Web SSO en consultant les journaux du tenant.

​

Journal de Token Exchange

• sertft : échange de jeton d’actualisation réussi. Ce journal correspond à un échange Native to Web SSO lorsque le champ audience est "audience":"urn:$auth0Domain:session_transfer"
• fertft: échange de jeton d’actualisation Failed. Ce journal correspond à un échange Native to Web SSO lorsque le champ audience est "audience": "urn:$auth0Domain:session_transfer"

​

Journaux d’avertissement de validation du transfert de session

Auth0 émet des journaux d’avertissement (w) lorsque la validation du jeton de transfert de session échoue lors de la requête /authorize. Ces journaux vous aident à diagnostiquer les problèmes liés à Native to Web SSO :

Description de l’événement	Cause
Single Sign-On failed: Session Transfer Token not found or expired. This may indicate token reuse or expiration.	Le jeton de transfert de session est introuvable, a déjà été utilisé ou a expiré (les jetons sont à usage unique et expirent après 1 minute).
Single Sign-On failed: Session Transfer Token device binding validation failed due to IP/ASN mismatch.	L’adresse IP ou l’ASN de la requête web ne correspond pas à l’association à l’appareil configurée pour le jeton de transfert de session.
Single Sign-On failed: Session Transfer Token organization mismatch detected.	Le paramètre organization dans la requête /authorize ne correspond pas à l’organisation du jeton de transfert de session.
Single Sign-On failed: Session Transfer Token user mismatch detected.	Une session Auth0 existante appartient à un autre utilisateur que celui du jeton de transfert de session.
Single Sign-On failed: Parent refresh token not found. Session Transfer Token won't be used for session establishment.	Le refresh token parent utilisé pour créer le jeton de transfert de session a été révoqué ou supprimé; le jeton de transfert de session ne sera donc pas utilisé pour établir la session.