Flux de code d’autorisation avec PKCE du SDK Auth0 Single Page App.

SDK Auth0 pour les applications monopage utilisant le flux de code d’autorisation avec PKCE.

Le SDK Auth0 pour applications monopages est une nouvelle bibliothèque JavaScript qui permet d’implémenter l’authentification et l’autorisation dans des applications monopages (SPA) avec Auth0. Il fournit une API de haut niveau et prend en charge une grande partie des détails afin que vous puissiez sécuriser les SPA selon les pratiques exemplaires tout en écrivant moins de code.

L’Auth0 SPA SDK gère les détails liés aux autorisations et aux protocoles, l’expiration et le renouvellement des jetons, ainsi que le stockage et la mise en cache des jetons. En arrière-plan, il implémente Universal Login et le flux de code d’autorisation avec PKCE.

La bibliothèque et la documentation de l’API sont hébergées sur GitHub.

Si vous rencontrez des problèmes ou des erreurs lors de l’utilisation du nouveau SDK JavaScript, veuillez consulter la FAQ pour voir si votre problème y est déjà traité.

Installation

Vous avez plusieurs options pour utiliser le Auth0 SPA SDK dans votre projet :

• À partir du CDN : <script src="https://cdn.auth0.com/js/auth0-spa-js/2.0/auth0-spa-js.production.js"></script>. Pour en savoir plus, consultez la FAQ.
• Avec npm : npm install @auth0/auth0-spa-js
• Avec yarn : yarn add @auth0/auth0-spa-js

Premiers pas

Créer l’application

Vous devez d’abord créer une nouvelle instance de l’objet client Auth0Client. Créez l’instance Auth0Client avant d’effectuer le rendu ou d’initialiser votre application. Vous pouvez le faire à l’aide de la méthode async/await ou de promesses. Vous ne devez créer qu’une seule instance du client.

L’utilisation de createAuth0Client fait automatiquement quelques opérations :

• Crée une instance de Auth0Client.
• Appelle getTokenSilently pour actualiser la session de l’utilisateur.
• Supprime toutes les erreurs de getTokenSilently, sauf login_required.

Utilisez async/await

Utiliser des promesses

Vous pouvez aussi créer l’application directement à l’aide du constructeur Auth0Client. Cela peut être utile si vous voulez :

• Éviter l’appel à getTokenSilently lors de l’initialisation.
• Gérer les erreurs de façon personnalisée.
• Initialiser le SDK de manière synchrone.

Connectez-vous et obtenez les informations de l’utilisateur

Ensuite, créez un bouton sur lequel les utilisateurs peuvent cliquer pour lancer la connexion :

<button id="login">Click to Login</button>

Écoutez les événements de clic sur le bouton que vous avez créé. Lorsque l’événement se produit, utilisez la méthode de connexion souhaitée pour authentifier l’utilisateur (loginWithRedirect() dans cet exemple). Une fois l’utilisateur authentifié, vous pouvez récupérer le profil utilisateur à l’aide de la méthode getUser().

Utilisez async/await

document.getElementById('login').addEventListener('click', async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
  //connecté. vous pouvez obtenir le profil utilisateur comme suit :
  const user = await auth0.getUser();
  console.log(user);
});

Utiliser des promesses

document.getElementById('login').addEventListener('click', () => {
  auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  }).then(token => {
    //connecté. vous pouvez obtenir le profil utilisateur comme suit :
    auth0.getUser().then(user => {
      console.log(user);
    });
  });
});

Appeler une API

Pour appeler votre API, commencez par obtenir le jeton d’accès de l’utilisateur. Utilisez ensuite ce jeton d’accès dans votre requête. Dans cet exemple, la méthode getTokenSilently est utilisée pour récupérer le jeton d’accès :

<button id="callApi">Call an API</button>

Utiliser async/await

document.getElementById('callApi').addEventListener('click', async () => {
  const accessToken = await auth0.getTokenSilently();
  const result = await fetch('https://exampleco.com/api', {
    method: 'GET',
    headers: {
      Authorization: 'Bearer ' + accessToken
    }
  });
  const data = await result.json();
  console.log(data);
});

Utiliser des promesses

document.getElementById('callApi').addEventListener('click', () => {
  auth0
    .getTokenSilently()
    .then(accessToken =>
      fetch('https://exampleco.com/api', {
        method: 'GET',
        headers: {
          Authorization: 'Bearer ' + accessToken
        }
      })
    )
    .then(result => result.json())
    .then(data => {
      console.log(data);
    });
});

Déconnexion

Ajoutez un bouton sur lequel les utilisateurs peuvent cliquer pour se déconnecter :

<button id="logout">Logout</button>

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

Modifier les options de stockage

Par défaut, le Auth0 SPA SDK stocke les jetons en mémoire. Toutefois, cela n’assure pas la persistance entre les rechargements de page et les onglets du navigateur. Vous pouvez plutôt choisir de stocker les jetons dans le stockage local en définissant la propriété cacheLocation sur localstorage lors de l’initialisation du SDK. Cela peut aider à atténuer certains effets des technologies de protection de la vie privée du navigateur qui empêchent l’accès au cookie de session d’Auth0, en conservant les jetons d’accès plus longtemps.

Le stockage des jetons dans le stockage local du navigateur assure la persistance entre les rechargements de page et les onglets du navigateur. Toutefois, si un attaquant parvient à exécuter du JavaScript dans la SPA au moyen d’une attaque par script intersite (XSS), il peut récupérer les jetons stockés dans le stockage local. Une vulnérabilité menant à une attaque XSS réussie peut se trouver soit dans le code source de la SPA, soit dans tout code JavaScript tiers (comme Bootstrap, jQuery ou Google Analytics) inclus dans la SPA.

Pour en savoir plus, consultez le stockage des jetons.

Utiliser des jetons d’actualisation avec rotation

Le Auth0 SPA SDK peut être configuré pour utiliser des jetons d’actualisation avec rotation afin d’obtenir silencieusement de nouveaux jetons d’accès. Ils permettent de contourner les mécanismes de confidentialité des navigateurs qui empêchent l’accès au cookie de session d’Auth0 lors d’une authentification silencieuse, tout en offrant une détection intégrée de la réutilisation.

Configurez le SDK en définissant useRefreshTokens sur true lors de l’initialisation :

Jetons d’actualisation devront aussi être configurés pour votre locataire avant de pouvoir être utilisés dans votre SPA.

Une fois configurés, le SDK demandera le scope offline_access à l’étape d’autorisation. De plus, getTokenSilently appellera alors directement le point de terminaison /oauth/token pour échanger des jetons d’actualisation contre des jetons d’accès. Le SDK respectera la configuration de stockage au moment d’enregistrer les jetons d’actualisation. Si le SDK a été configuré avec le mécanisme de stockage en mémoire par défaut, les jetons d’actualisation seront perdus lorsque la page sera rechargée.

Utilisation

Vous trouverez ci-dessous des exemples d’utilisation de différentes méthodes du SDK. Notez que jQuery est utilisé dans ces exemples.

Connexion par redirection

Redirigez vers le point de terminaison /authorize d’Auth0 pour lancer le flux Universal Login :

$('#loginRedirect').click(async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
});

Connexion avec une fenêtre contextuelle

Utilisez une fenêtre contextuelle pour vous connecter à l’aide de la page Universal Login :

$('#loginPopup').click(async () => {
  await auth0.loginWithPopup();
});

Si l’utilisateur met plus que le délai d’expiration par défaut de 60 secondes pour terminer le flux d’authentification, l’authentification sera interrompue et vous devrez intercepter l’erreur dans votre code pour :

Suggérer à l’utilisateur de réessayer et de fermer manuellement la fenêtre contextuelle à l’aide de error.popup.close :

$('#loginPopup').click(async () => {
  try {
    await auth0.loginWithPopup();
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // logique personnalisée pour informer l'utilisateur de réessayer
    error.popup.close();
  }
});

Ou créez une option popup personnalisée dans l’objet options :

$('#loginPopup').click(async () => {
  const popup = window.open(
    '',
    'auth0:authorize:popup',
    'left=100,top=100,width=400,height=600,resizable'
  );
  try {
    await auth0.loginWithPopup({ popup });
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // logique personnalisée pour informer l'utilisateur de réessayer
    error.popup.close();
  }
});

Connexion avec callback après redirection

Lorsque le navigateur est redirigé depuis Auth0 vers votre SPA, handleRedirectCallback doit être appelé pour terminer le flux de connexion :

$('#loginRedirectCallback').click(async () => {
  await auth0.handleRedirectCallback();
});

Obtenir un Jeton d’accès sans interaction

Obtenez un nouveau Jeton d’accès silencieusement à l’aide d’un iframe masqué et de prompt=none, ou en utilisant un Jeton d’actualisation rotatif. Les Jetons d’actualisation sont utilisés lorsque useRefreshTokens est défini sur true lors de la configuration du SDK.

L’obtention silencieuse d’un Jeton d’accès sans utiliser de Jetons d’actualisation ne fonctionne pas dans les navigateurs qui bloquent les témoins tiers, comme Safari et Brave. Pour en savoir plus sur la solution de contournement avec un Domaine personnalisé, consultez Troubleshoot Renew Tokens When Using Safari.

Si le stockage en mémoire (par défaut) et les jetons d’actualisation sont utilisés, les nouveaux jetons sont récupérés au moyen d’un worker Web dans les navigateurs pris en charge :

$('#getToken').click(async () => {
  const token = await auth0.getTokenSilently();
});

La méthode getTokenSilently() exige que l’option Allow Skipping User Consent soit activée dans vos paramètres d’API dans le Auth0 Dashboard. De plus, le consentement de l’utilisateur ne peut pas être ignoré sur « localhost ».

Obtenir un jeton d’accès au moyen d’une fenêtre contextuelle

Les jetons d’accès peuvent aussi être obtenus au moyen d’une fenêtre contextuelle. Contrairement à getTokenSilently, cette méthode pour obtenir un jeton d’accès fonctionne dans les navigateurs où les témoins tiers sont bloqués par défaut :

$('#getTokenPopup').click(async () => {
  const token = await auth0.getTokenWithPopup({
    authorizationParams: {
      audience: 'https://mydomain/api/',
      scope: 'read:rules'
    }
  });
});

Obtenir un jeton d’accès pour une audience différente

Vous pouvez transmettre des options à getTokenSilently pour obtenir un jeton d’accès avec une audience et un scope différents de ceux demandés au moment de l’authentification de l’utilisateur.

Cela fonctionne uniquement si vous n’utilisez pas de jetons d’actualisation (useRefreshTokens: false), car un jeton d’actualisation est lié à l’audience et au scope précis demandés au moment de l’authentification de l’utilisateur.

$('#getToken_audience').click(async () => {
  const differentAudienceOptions = {
    authorizationParams: {
      audience: 'https://mydomain/another-api/',
      scope: 'read:rules',
      redirect_uri: 'http://localhost:3000/callback.html'
    }
  };
  const token = await auth0.getTokenSilently(differentAudienceOptions);
});

Récupérer l’utilisateur

Vous pouvez récupérer les données de profil de l’utilisateur authentifié en appelant la méthode getUser :

$('#getUser').click(async () => {
  const user = await auth0.getUser();
});

Obtenir les claims de l’ID Token

Vous pouvez obtenir les claims de l’ID Token de l’utilisateur authentifié en appelant la méthode getIdTokenClaims :

$('#getIdTokenClaims').click(async () => {
  const claims = await auth0.getIdTokenClaims();
  // si vous avez besoin du id_token brut, vous pouvez y accéder
  // via la propriété __raw
  const id_token = claims.__raw;
});

Déconnexion (par défaut)

Vous pouvez lancer une déconnexion en appelant la méthode logout :

$('#logout').click(async () => {
  auth0.logout({
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

Déconnexion sans ID client

Vous pouvez lancer une déconnexion sans préciser d’ID client en appelant la méthode logout et en incluant clientId: null :

$('#logoutNoClientId').click(async () => {
  auth0.logout({
    clientId: null,
    logoutParams: {
      returnTo: 'http://localhost:3000/'
    }
  });
});

En savoir plus

• Valider les jetons d’accès