Trousse SDK Auth0 pour les applications à page unique (SPA)

La trousse SDK Auth0 pour les applications à page unique (SPA) est une nouvelle bibliothèque JavaScript pour la implémentation de l’authentification et de l’autorisation dans les applications à page unique (SPA) avec Auth0. Il fournit une API de haut niveau et gère une grande partie des détails afin que vous puissiez sécuriser les SPA en utilisant les meilleures pratiques, tout en écrivant moins de code.

La trousse SDK Auth0 pour les applications à page unique (SPA) gère les détails de l’autorisation et du protocole, l’expiration et le renouvellement des jetons, ainsi que le stockage et la mise en cache des jetons. En arrière-plan, il met en œuvre la connexion universelle et le flux d’octroi 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 de la nouvelle trousse SDK pour JavaScript, veuillez lire la FAQ pour voir si votre problème y est traité.

Vous avez plusieurs options pour utiliser la trousse SDK Auth0 pour les applications à page unique (SPA) dans votre projet :

• Depuis le CDN : <script src="https://cdn.auth0.com/js/auth0-spa-js/2.0/auth0-spa-js.production.js"></script>. Pour plus d’informations, lisez la FAQ.

• Avec npm : npm install @auth0/auth0-spa-js

• Avec yarn : yarn add @auth0/auth0-spa-js

Tout d’abord, vous devez 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 en utilisant soit la méthode async/await, soit les promesses. Vous ne devez créer qu’une seule instance du client.

L’utilisation de createAuth0Client permet de réaliser plusieurs choses automatiquement :

• Elle crée une instance de Auth0Client.

• Elle appelle getTokenSilently pour actualiser la session de l’utilisateur.

• Elle supprime toutes les erreurs provenant de getTokenSilently, à l’exception de login_required.

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

const auth0 = await createAuth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}'
});

createAuth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}'
}).then(auth0 => {
  //...
});

Vous pouvez également créer le client directement en utilisant le constructeur Auth0Client. Cela peut être utile si vous souhaitez :

• Contourner l’appel à getTokenSilently lors de l’initialisation.

• Effectuer une gestion personnalisée des erreurs.

• Initialiser la trousse SDK de manière synchrone.

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

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

Ensuite, créez un bouton sur lequel les utilisateurs peuvent cliquer pour commencer à se connecter :

<button id="login">Cliquer pour se connecter</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().

document.getElementById('login').addEventListener('click', async () => {
  await auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  });
  //logged in. you can get the user profile like this:
  const user = await auth0.getUser();
  console.log(user);
});

document.getElementById('login').addEventListener('click', () => {
  auth0.loginWithRedirect({
    authorizationParams: {
      redirect_uri: 'http://localhost:3000/'
    }
  }).then(token => {
    //logged in. you can get the user profile like this:
    auth0.getUser().then(user => {
      console.log(user);
    });
  });
});

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

<button id="callApi">Appeler une API</button>

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);
});

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);
    });
});

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

<button id="logout">Déconnexion</button>

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

Par défaut, la trousse SDK Auth0 pour les applications à page unique (SPA) stocke les jetons en mémoire. Toutefois, cette méthode ne permet pas d’assurer la persistance de l’information entre les actualisations de pages et les onglets du navigateur. Au lieu de cela, vous pouvez choisir de stocker les jetons dans le stockage local en définissant la propriété cacheLocation sur localstorage lors de l’initialisation de la trousse SDK. Cela peut contribuer à atténuer certains des effets de la technologie de protection de la vie privée des navigateurs qui empêche l’accès au témoin de session Auth0 en stockant les jetons d’accès plus longtemps.

const auth0 = await createAuth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
  cacheLocation: 'localstorage'
});

La trousse SDK Auth0 pour les applications à page unique (SPA) pour application monopage peut être configurée pour utiliser une rotation des jetons d’actualisation afin d’obtenir silencieusement de nouveaux jetons d’accès. Ils peuvent être utilisés pour contourner la technologie de confidentialité du navigateur qui empêche l’accès au témoin de session Auth0 lors d’une authentification silencieuse, ainsi que pour fournir une détection de réutilisation intégrée.

Pour ce faire, configurez la trousse SDK en définissant useRefreshTokens sur true lors de l’initialisation :

const auth0 = await createAuth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
  useRefreshTokens: true
});

// Request a new access token using a refresh token
const token = await auth0.getTokenSilently();

Les jetons d’actualisation devront également être configurés pour votre locataire avant de pouvoir être utilisés dans votre application monopage (SPA).

Une fois configuré, la trousse SDK demandera la permission offline_access pendant l’étape d’autorisation. En outre, getTokenSilently appellera alors le point de terminaison /oauth/token directement pour échanger des jetons d’actualisation contre des jetons d’accès. Le SDK respectera la configuration de stockage lors du stockage des jetons d’actualisation. Si le SDK a été configuré en utilisant le mécanisme de stockage en mémoire par défaut, les jetons d’actualisation seront perdus lors de l’actualisation de la page.

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

Redirigez vers le point de terminaison /authorize à Auth0, en démarrant le flux de connexion universelle :

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

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

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

Si l’utilisateur prend plus de temps que le délai par défaut de 60 secondes pour compléter le flux d’authentification, l’authentification sera interrompue et vous devrez gérer l’erreur dans votre code :

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

$('#loginPopup').click(async () => {
  try {
    await auth0.loginWithPopup();
  } catch {error}
  if (error instanceof auth0.PopupTimeoutError) {
    // custom logic to inform user to retry
    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) {
    // custom logic to inform user to retry
    error.popup.close();
  }
});

Lorsque le navigateur est redirigé d’Auth0 vers votre application monopage, handleRedirectCallback doit être appelé afin de compléter le flux de connexion :

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

Obtenir un nouveau jeton d’accès silencieusement en utilisant une iframe cachée et 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 de la trousse SDK.

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 à l’aide d’un agent web sur les navigateurs pris en charge :

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

La méthode getTokenSilently() nécessite que Autoriser le contournement du consentement utilisateur soit activé dans vos Paramètres API dans Dashboard. En outre, le consentement de l’utilisateur ne peut pas être ignoré sur ’localhost’.

Les jetons d’accès peuvent également être récupérés à l’aide d’une fenêtre contextuelle. Contrairement à getTokenSilently, cette méthode de récupération d’un jeton d’accès fonctionnera dans les navigateurs dont 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'
    }
  });
});

Des options peuvent être transmises à getTokenSilently pour obtenir un jeton d’accès dont l'audience et la permission diffèrent de ceux 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);
});

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

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

Vous pouvez obtenir les demandes du jeton d’ID de l’utilisateur authentifié en appelant la méthode getIdTokenClaims :

$('#getIdTokenClaims').click(async () => {
  const claims = await auth0.getIdTokenClaims();
  // if you need the raw id_token, you can access it
  // using the __raw property
  const id_token = claims.__raw;
});

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

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

Vous pouvez lancer une action de déconnexion sans spécifier 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/'
    }
  });
});

• Valider les jetons d’accès