Auth0 Single Page App SDK : flux d’octroi de code avec PKCE.

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

Auth0 Single Page App SDK est une nouvelle bibliothèque Javascript conçue pour mettre en œuvre l’authentification et l’autorisation dans des applications monopages (SPA) avec Auth0. Elle fournit une API de haut niveau et prend en charge une bonne partie des détails, afin que vous puissiez sécuriser les SPA selon les pratiques exemplaires tout en écrivant moins de code.

Auth0 SPA SDK gère les détails liés aux types d’octroi et au protocole, l’expiration et le renouvellement des tokens, ainsi que le stockage des tokens et la mise en cache. En coulisses, il implémente Universal Login et le flux d’octroi de code 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 vérifier si votre problème y est déjà traité.

Installation

Vous avez plusieurs options pour utiliser l’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 le client

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

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

• Elle crée une instance d’Auth0Client.
• Elle appelle getTokenSilently pour actualiser la session de l’utilisateur.
• Elle ignore toutes les erreurs de getTokenSilently, sauf login_required.

Utilisez async/await

Utiliser les promesses

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

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

Se connecter et obtenir les renseignements sur 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 du 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 son profil à l’aide de la méthode getUser().

Utiliser async/await

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

Utiliser les 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 le 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 les 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 permettant aux utilisateurs de 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, l’Auth0 SPA SDK stocke les jetons en mémoire. Toutefois, cela ne permet pas de les conserver d’une actualisation de page à l’autre ni entre 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 des navigateurs qui empêchent l’accès au cookie de session Auth0 en conservant les jetons d’accès plus longtemps.

Le stockage des jetons dans le stockage local du navigateur permet de les conserver entre les actualisations de page et les onglets du navigateur. Toutefois, si un attaquant parvient à exécuter du JavaScript dans la SPA au moyen d’une attaque de 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

L’Auth0 SPA SDK peut être configuré pour utiliser des jetons d’actualisation avec rotation afin d’obtenir silencieusement de nouveaux jetons d’accès. Ceux-ci peuvent servir à contourner les technologies 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 à true lors de l’initialisation :

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

Une fois configurés, le SDK demandera la portée offline_access pendant 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 au rechargement de la page.

Utilisation

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

Connexion par redirection

Redirigez vers l’endpoint /authorize d’Auth0 pour lancer le flux Universal Login :

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

Se connecter avec une fenêtre contextuelle

Utilisez une fenêtre contextuelle pour vous connecter au moyen de la page Universal Login :

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

Si l’utilisateur met plus de 60 secondes, soit le délai d’expiration par défaut, 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 de redirection

Lorsque le navigateur est redirigé d’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 sans interaction à l’aide d’un iframe masqué avec prompt=none, ou d’un jeton d’actualisation avec rotation. Les jetons d’actualisation sont utilisés lorsque useRefreshTokens est défini sur true lors de la configuration du SDK.

L’obtention d’un jeton d’accès sans interaction, sans utiliser de jetons d’actualisation, ne fonctionnera pas dans les navigateurs qui bloquent les cookies tiers, comme Safari et Brave. Pour en savoir plus sur cette solution de contournement au moyen d’un domaine personnalisé, consultez Résoudre les problèmes de renouvellement de jetons lors de l’utilisation de Safari.

Si le stockage en mémoire (par défaut) et des jetons d’actualisation sont utilisés, les nouveaux jetons sont récupérés au moyen d’un Web Worker 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 les paramètres de votre API dans le 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 récupérés au moyen d’une fenêtre contextuelle. Contrairement à getTokenSilently, cette méthode de récupération d’un jeton d’accès fonctionne dans les navigateurs où les cookies 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

Des options peuvent être transmises à getTokenSilently pour obtenir un jeton d’accès avec une audience et une portée différentes de celles demandées lors de l’authentification de l’utilisateur.

Cela fonctionne uniquement si vous n’utilisez pas de jeton d’actualisation (useRefreshTokens: false), puisqu’un jeton d’actualisation est lié à l’audience et à la portée précises demandées lors 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 du 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 initier 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