Configurer et mettre en œuvre le SSO natif vers le Web

Découvrez comment configurer vos applications pour utiliser le SSO natif vers le Web.

​

Configurer le SSO natif vers le Web

Pour utiliser le SSO natif vers le Web, configurez vos applications natives et Web (Single Page App ou Regular Web App) pour créer et gérer des sessions avec la Management API d’Auth0.

Vous devez disposer d’un jeton d’accès pour utiliser la Management API ou Auth0 CLI.

Pour configurer le SSO natif vers le Web, vous devez créer et gérer des session_transfer_tokens et configurer vos applications natives et Web.

Le SSO natif vers le Web prend en charge les SDK suivants : Auth0 Android SDK, Auth0 Swift SDK et Auth0 React Native SDK.

La prise en charge du SSO natif vers le Web est offerte dans les outils suivants : Auth0 Deploy CLI, Auth0 Terraform Provider et Auth0 CLI.

Le SSO natif vers le Web prend en charge tout flux d’authentification qui renvoie un jeton d’actualisation, comme Resource Owner Password Flow et Authorization Code Flow with Proof Key for Code Exchange.

​

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 au moyen de cookies ou d’un paramètre d’URL
• Lier la session à l’appareil d’un utilisateur à l’aide d’une adresse IP ou d’un ASN

Pour les applications existantes, effectuez un appel PATCH au point de terminaison Update a Client. Pour créer une nouvelle application, effectuez un appel 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 d’identité et, éventuellement, 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 cookies, 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 de 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 avec Auth0 CLI :

​

Configurer les applications Web

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

• Mettez à jour votre application Web à l’aide d’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 en choisissant 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 Mettre à jour une application :

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

​

Implémenter le SSO natif vers le Web

Le SSO unique natif vers le Web offre une expérience fluide en permettant de faire passer les 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, puis transmettre ce jeton de transfert de session à votre application Web, au moyen d’une URL ou d’un témoin, afin d’autoriser la session.

• Si allow_refresh_token est désactivé dans l’application, mais que l’application demande offline_access, Auth0 n’émet pas de refresh_token, mais l’authentification fonctionne quand même.

• Si la rotation des Jetons d’actualisation est activée, Auth0 renvoie un nouveau refresh_token dans l’appel d’échange de jeton. L’échange du Jeton d’actualisation doit avoir lieu immédiatement 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 des SDK Swift, Android ou 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érer l’erreur
        }
    }
)

SDK React Native

// Utilisation de 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);
    }
  };
}

// Utilisation de 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 d’HTTP :

Ces exemples utilisent des espaces réservés pour les valeurs dynamiques. Remplacez-les par votre domaine Auth0, votre client_id et un refresh_token existant.

Le locataire Auth0 renvoie un session_transfer_token à usage unique, de courte durée (valide pendant une 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 pendant l’authentification, cet appel renverra aussi un ID Token.

​

Étape 2 : Envoyez le jeton de transfert de session par URL ou par cookie

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

Option 1 : Envoyer le session_transfer_token comme cookie

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

• Ajouter le session_transfer_token dans un cookie.
• Ouvrir l’application web au moyen de WebView ou d’un navigateur.
• Connecter l’application web à votre locataire Auth0 ou à votre Domaine personnalisé. Comme le session_transfer_token est inclus dans le cookie, l’utilisateur n’a pas à s’authentifier avec le premier facteur.

Option 2 : Envoyer le session_transfer_token en tant que paramètre d’URL

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

• Ajouter le session_transfer_token en tant que paramètre d’URL.
• Ouvrir l’application web à l’aide de WebView ou d’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 locataire Auth0 authentifie l’utilisateur sans exiger d’authentification du 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 requise, puisque le navigateur envoie le cookie dans la requête au point de terminaison /authorize.

Implémentez le SSO Native to Web Web Single 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 paramètre d’URL session_transfer_token est transmis.

​

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

Les SDK Auth0 ne prennent pas automatiquement en charge la fonctionnalité Native to Web Single SSO et n’incluent pas le session_transfer_token dans la requête adressée au point de terminaison /authorize.

Vous trouverez ci-dessous des exemples d’applications web utilisant les SDK Auth0 pour transmettre le session_transfer_token dans la requête adressée au 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 du middleware session_transfer_token.

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 de state
  const config = { ...baseConfig };

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

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

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

Si votre application web utilise le SDK SPA d’Auth0, vous pouvez transmettre le session_transfer_token à loginWithRedirect() dans 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,
    },
  });
}

SDK React d’Auth0 (@auth0/auth0-react)

Si votre application web utilise le SDK React d’Auth0, vous pouvez utiliser loginWithRedirect 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 Auth0 /authorize, et le redirect_uri correspond à l’URL de connexion SAML ou WS-Fed.

​

SSO natif vers le Web avec les Organisations

Le SSO natif vers le Web prend en charge les Organisations. 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 les Organisations avec le SSO natif vers le Web, le paramètre organization de la requête /authorize de l’application Web doit correspondre à l’organisation associée au jeton de transfert de session. En cas de non-correspondance, l’authentification échouera et l’utilisateur devra se reconnecter.

Pour utiliser les Organisations avec le SSO natif vers le Web :

1. Authentifiez l’utilisateur dans votre application native auprès d’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 dans la requête /authorize ne correspond pas à l’organisation dans le jeton de transfert de session, le jeton de transfert de session est rejeté et l’utilisateur est redirigé vers la page de connexion pour se réauthentifier. Un avertissement est consigné dans les journaux de votre locataire avec la description d’événement “Échec de l’authentification unique : non-correspondance de l’organisation détectée dans le jeton de transfert de session.”

​

Jeton de transfert de session avec Actions

L’utilisation de session_transfer_token avec Actions vous permet de configurer des fonctionnalités de détection et de réponse aux risques après l’authentification afin de renforcer la protection des utilisateurs.

À cette fin, l’objet d’Action post-login event.session_transfer_token fournit des informations pertinentes, 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 Déclencheurs d’Actions : post-login - objet Event.

Le code d’Action ci-dessous vous permet de refuser dynamiquement une transaction en fonction des informations 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

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

Auth0 expose ces informations dans les Actions Post Login par l’intermédiaire 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 SSO natif vers le Web, ces métadonnées sont automatiquement accessibles dans la session Web correspondante via Actions.

Le code de l’Action ci-dessous vous permet d’appliquer une logique d’accès conditionnel en fonction des métadonnées de confiance de l’appareil provenant de l’application native :

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) => {
  // Accéder aux métadonnées du jeton d'actualisation 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 aussi ajouter des revendications 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é de SSO natif vers le Web en consultant les journaux du locataire.

​

Journaux d’échange de jetons

• sertft : Échange réussi du Jeton d’actualisation. Ce journal correspond à un échange SSO du natif vers le Web lorsque le champ audience est "audience":"urn:$auth0Domain:session_transfer"
• fertft: Échec de l’échange du Jeton d’actualisation. Ce journal correspond à un échange SSO du natif vers le Web lorsque le champ audience est "audience": "urn:$auth0Domain:session_transfer"

​

Journaux d’avertissement de validation du transfert de session

Auth0 génère 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 à résoudre les problèmes de SSO du natif vers le Web :

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 à la liaison de 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 préexistante appartient à un utilisateur différent de celui associé au 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 jeton d’actualisation parent utilisé pour créer le jeton de transfert de session a été révoqué ou supprimé.