Référence Auth0.js v9

Auth0.js est une bibliothèque du côté client d’Auth0. Il est recommandé de l’utiliser en conjonction avec la connexion universelle, qui devrait être utilisée chaque fois que possible. Utiliser auth0.js dans votre SPA rend plus facile l’authentification et l’autorisation avec Auth0.

La documentation complète API pour la bibliothèque est accessible ici.

Le répertoire d’exemples de la bibliothèque auth0.js est une application prête à l’utilisation qui peut vous aider à essayer auth0.js efficacement et facilement. Pour l’exécuter, suivez ces étapes simples :

1. Si vous n’avez pas installé node, faites-le maintenant

2. Téléchargez les dépendances en exécutant npm install à partir de la racine de ce projet.

3. Enfin, exécutez npm start à partir du répertoire racine de ce projet, et naviguez vers votre application, sur le node server, par exemple http://localhost:3000/example.

Maintenant, débutons en intégrant auth0.js dans votre projet. Nous couvrirons les méthodes d’installation, l’initialisation de auth0.js, l’inscription, la connexion, la déconnexion, et plus encore!

Lors de la mise en œuvre de la connexion intégrée, la bibliothèque utilisera des appels entre origines à l’intérieur d’iframes cachés pour effectuer l’authentification. Pour garantir que cela peut être réalisé en toute sécurité, Auth0 a besoin de connaître les domaines où vous hébergerez vos applications.

Ajoutez le domaine au champ Origines Web autorisées. Vous pouvez trouver ce champ dans la zone Application Settings (Paramètres de l’application) de votre Dashboard (Tableau de bord).

Vous avez quelques options pour utiliser auth0.js dans vos projets. Choisissez l’une des options suivantes, selon vos besoins :

Installation via npm ou yarn :

npm install auth0-js

yarn add auth0-js

Après avoir installé le module auth0-js, vous devrez le regrouper avec toutes ses dépendances, ou l’importer à l’aide de :

import auth0 from 'auth0-js';

Alternativemet, incluez le script via notre CDN :

<script src="https://cdn.auth0.com/js/auth0/9.18/auth0.min.js"></script>

initialisez une nouvelle requête de l’application Auth0, tel que suit :

<script type="text/javascript">
  var webAuth = new auth0.WebAuth({
    domain:       '{yourDomain}',
    clientID:     '{yourClientId}'
  });
</script>

Deux paramètres obligatoires doivent être transmis dans l’objet options lors de l’instanciation de webAuth, tandis que d’autres sont facultatifs.

Dans auth0.js v9, la valeur par défaut de scope est openid profile email.

Vous pouvez choisir une méthode de connexion fondée sur le type d’auth dont vous avez besoin dans votre application.

La méthode authorize() peut être utilisée pour connecter les utilisateurs au moyen de la connexion universelle, ou à l’aide des connexions par réseau social, tel que montré dans les exemples ci-dessous. Cette méthode invoque le point de terminaison /authorize d’Authentication API et peut accepter un certain nombre de paramètres via l’objet options.

Pour une connexion hébergée, vous devez appeler la méthode /authorize(). webAuth.authorize({ //Any additional options can go here });

Pour les connexions par réseau social, le paramètre connection devra être indiqué : webAuth.authorize({ connection: ’twitter’ });

Pour l’authentification par fenêtre contextuelle, la méthode popup.authorize peut être utilisée. L’authentification par fenêtre contextuelle ne peut être utilisée dans les pages de connexion avec hôte. Typiquement, l’authentification par fenêtre contextuelle est utilisée par les applications avec une simple page, de manière à ce que l’état actuel ne soit pas perdu en effectuant une redirection de la page entière.

Autorisation par défaut avec fenêtre contextuelle (les utilisateurs voient la Connexion universelle Auth0) :

webAuth.popup.authorize({
  responseType: 'token'
  redirectUri: 'https://{yourApp}/popup_response_handler.html'
  //Any additional options can go here
}, function(err, authResult) {
  //do something
});

Et pour les connexions par réseau social avec fenêtre contextuelle utilisant authorize :

webAuth.popup.authorize({
  responseType: 'token'
  redirectUri: 'https://{yourApp}/popup_response_handler.html',
  connection: 'twitter'
}, function(err, authResult) {
  //do something
});

Lorsque vous utilisez l’authentification par fenêtre contextuelle, vous devez fournir un redirectUri où la page de destination communique les résultats de l’autorisation au rappel en utilisant la méthode webAuth.popup.callback. Une simple mise en oeuvre ressemblerait à ceci :

<!-- popup_response_handler.html -->
<html>
  <body>
    <script src="https://cdn.auth0.com/js/auth0/9.18/auth0.min.js"></script>
    <script type="text/javascript">
      var webAuth = new auth0.WebAuth({
        domain:       'YOUR_AUTH0_DOMAIN',
        clientID:     'YOUR_CLIENT_ID'
      });
      webAuth.popup.callback();
    </script>
  </body>
</html>

La méthode login permet une authentification cross-origin pour les connexions par base de données, en utilisant /co/authenticate.

webAuth.login({
  realm: 'tests',
  username: 'testuser',
  password: 'testpass',
});

La méthode crossOriginVerification() peut être utilisée pour aider à fournir une authentification cross-origin aux clients dont les témoins de tierce-partie ont été désactivés dans leur navigateur. Pour de plus amples détails concernant spn utilisation, consultez le document authentification cross-origin.

La méthode buildAuthorizeUrl peut être utilisée pour créer l’URL /authorize, afin d’initialiser une nouvelle transaction. Utilisez cette méthode si vous souhaitez mettre en place l’authentification (passive) sur navigateur.

// Calculate URL to redirect to
var url = webAuth.client.buildAuthorizeUrl({
  clientID: '{yourClientId}', // string
  responseType: 'token id_token', // code
  redirectUri: 'https://{yourApp}/callback',
  state: '{yourState}',
  nonce: '{yourNonce}'
});

// Redirect to url
// ...

Le paramètre state est une valeur opaque qu’Auth0 vous renverra. Cette méthode aide à prévenir les attaques CSRF, et elle doit être indiquée si vous redirigez vous-mêmes vers l’URL plutôt que d’appeler webAuth.authorize(). Pour plus d’informations, consultez la section Paramètre state.

Les applications avec connexion intégrée doivent remplir deux critères afin de bénéficier de l’Authentification unique (SSO).

1. Les deux applications tentant d’utiliser la SSO doivent être des applications de première partie. La SSO avec des applications tierces ne fonctionnera pas.

2. Elles doivent utiliser des domaines personnalisés et avoir à la fois les applications qui souhaitent bénéficier de la SSO et le locataire Auth0 sur le même domaine. Traditionnellement, les domaines Auth0 sont au format foo.auth0.com, mais les domaines personnalisés vous permettent d’utiliser le même domaine pour chacune des applications en question, ainsi que pour votre client Auth0, ce qui évite le risque d’attaques CSRF (Cross-Site Request Forgery).

Nous recommandons d’utiliser une connexion universelle au lieu de configurer la SSO dans des scénarios de connexion intégrée. La connexion universelle est la manière la plus fiable et stable de mettre en place la SSO, et c’est la seule option si vous devez utiliser plusieurs domaines pour vos applications, ou si vous utilisez des applications tiers.

L’authentification sans mot de passe permet aux utilisateurs de se connecter en recevant un mot de passe à usage unique (OTP) par courriel ou SMS. Ce processus demande que vous lanciez le processus Passwordless, produisant et envoyant un code à l’utilisateur, (ou un code avec un lien), suivi en acceptant les authentifiants par la méthode de vérification. Ce pourrait survenir sous la forme d’une écran de connexion qui demande leur (courriel ou numéro de téléphone) et le code que vous venez de leur envoyer. Ce pourrait également être mis en place sous la forme d’un lien Sans mot de passe avec un code envoyé à l’utilisateur. Ils n’auraient qu’à cliquer sur le lien dans leur couriel et ils atteindraient votre point de terminaison, pour alors vérifier ces données automatiquement à l’aide la même méthode de vérification (sans entrée manuelle de code de la part de l’utilisateur).

De manière à pouvoir utiliser l’authentification sans mot de passe, vous devrez initialiser auth0.js avec un redirectUri et définir le responseType : ’token’.

var webAuth = new auth0.WebAuth({
  clientID: '{yourClientId}',
  domain: '{yourDomain}',
  redirectUri: 'http://example.com',
  responseType: 'token id_token'
});

La première étape de l’authentification sans mot de passe avec auth0.js est la méthode passwordlessStart, qui a plusieurs paramètres qui peuvent être transmis dans son objet options :

webAuth.passwordlessStart({
    connection: 'email',
    send: 'code',
    email: 'foo@bar.com'
  }, function (err,res) {
    // handle errors or continue
  }
);

Si vous envoyez un code, vous devrez alors envoyer une demande à l’utilisateur d’entrer ce code. Vous traiterez le code et authentifierez l’utilisateur à l’aide de la méthode passwordlessLogin, qui possède plusieurs paramètres pouvant être envoyés dans son objet options :

Comme pour passwordlessStart, un seul des paramètres facultatifs phoneNumber et email doit être envoyé afin de vérifier la transaction sans mot de passe.

Pour pouvoir utiliser la méthode passwordlessLogin, les options redirectUri et responseType doivent être précisées au moment d’initialiser WebAuth.

webAuth.passwordlessLogin({
    connection: 'email',
    email: 'foo@bar.com',
    verificationCode: '389945'
  }, function (err,res) {
    // handle errors or continue
  }
);

Après l’authentification, vous pouvez utiliser la méthode parseHash pour analyser le fragment de hashage URL lorsque l’utilisateur est redirigé vers l’application pour extraire le résultat d’une réponse d’authentification Auth0. Vous pouvez choisir de gérer cette page de rappel, laquelle vous redirigera vers l’application principale ou au sein de la même page, selon les circonstances de la situation.

La méthode parseHash accepte un objet options qui contient les paramètres suivants :

Le contenu de l’objet authResult renvoyé par la méthode parseHash dépend des paramètres d’authentification utilisés. Ce peut comprendre :

webAuth.parseHash({ hash: window.location.hash }, function(err, authResult) {
  if (err) {
    return console.log(err);
  }

  webAuth.client.userInfo(authResult.accessToken, function(err, user) {
    // Now you have the user's information
  });
});

{
    "sub": "auth0|123456789012345678901234",
    "nickname": "johnfoo",
    "name": "johnfoo@gmail.com",
    "picture": "https://gravatar.com/avatar/example.png",
    "updated_at": "2018-05-07T14:16:52.013Z",
    "email": "johnfoo@gmail.com",
    "email_verified": "false"
}

Vous pouvez maintenant faire quelque chose d’autre avec cette information, selon les besoins de votre application, tel que d’acquérir l’ensemble des informations de profil de l’utilisateur dans Management API, tel que décrit ci-dessous.

Par défaut (et si responseType contient id_token), auth0.js génère un nonce aléatoire lorsque vous appelez webAuth.authorize, le stocke localement, et l’extrait dans webAuth.parseHash. Le comportement par défaut devrait fonctionner dans la majorité des cas, mains certains cas exigent au développeur de contrôler le nonce. Si vous souhaitez utiliser un nonce généré par le développeur, vous devez le fournir en tant qu’option à webAuth.authorize et webAuth.parseHash. webAuth.authorize({nonce: ’1234’, responseType: ’token id_token’}); webAuth.parseHash({nonce: ’1234’}, callback);

Si vous appelez webAuth.checkSession au lieu de webAuth.authorize, il vous suffit de définir votre nonce personnalisé en tant qu’option de checkSession :

webAuth.checkSession({
  nonce: '1234',
}, function (err, authResult) {
    ...
});

La méthode webAuth.checkSession vérifiera automatiquement que la demande nonce du jeton d’ID renvoyé est la même que celle de l’option.

Lorsque Auth0.js est employé pour une connexion intégrée, le point de terminaison /co/authenticate est utilisé, ce qui peut produire les erreurs suivantes :

Pour déconnecter un utilisateur, utilisez la méthode logout(). Cette méthode accepte l’objet options, lequel peut inclure les paramètres suivants :

Si le paramètre clientID est inclus, l’URL returnTo qui est fournie doit être listée dans les URL de déconnexion autorisées de l’application dans Auth0 Dashboard. Toutefois, si le paramètre clientID n’est pas inclus, l’URL returnTo doit figurer dans les URL de déconnexion autorisées.

webAuth.logout({
  returnTo: 'some url here',
  clientID: 'some client ID here'
});

Pour enregistrer un utilisateur, utilisez la méthode signup. Cette méthode accepte l’objet options, lequel peut inclure les paramètres suivants :

Les enregistrements devraient être pour les connexions de bases de données. Voici un exemple de la méthode signup et un exemple de code pour un formulaire.

<h2>Signup Database Connection</h2>
<input class="signup-email" />
<input type="password" class="signup-password" />
<input type="button" class="signup-db" value="Signup!" />
<script type="text/javascript">
    $('.signup-db').click(function (e) {
        e.preventDefault();
        webAuth.signup({
            connection: 'Username-Password-Authentication',
            email: $('.signup-email').val(),
            password: $('.signup-password').val(),
            user_metadata: { plan: 'silver', team_id: 'a111' }
        }, function (err) {
            if (err) return alert('Something went wrong: ' + err.message);
            return alert('success signup without login!')
        });
    });
</script>

La méthode checkSession vous permet d’acquérir un nouveau jeton auprès d’Auth0 pour un utilisateur qui est déjà authentifié auprès d’Auth0 pour votre domaine. La méthode accepte tous paramètres OAuth2 qui seraient normalement envoyés à authorize. Si vous les oubliez, les paramètres utilisés seront ceux fournis au moment de l’initialisation d’Auth0.

L’appel à checkSession peut être utilisé pour obtenir un nouveau jeton pour l’API définie en tant qu'audience lors de l’initialisation de webAuth :

webAuth.checkSession({}, function (err, authResult) {
  // err if automatic parseHash fails
  ...
});

Consultez Effectuer une extraction de AuthResult et obtenir des informations utilisateur pour connaître le format de authResult.

Sinon, le jeton peut être acquis pour une API différente que celle utilisée au moment d’initialiser webAuth en précisant un audience et une scope :

webAuth.checkSession(
  {
    audience: `https://mydomain/another-api/˜`,
    scope: 'read:messages'
  }, function (err, authResult) {
  // err if automatic parseHash fails
  ...
});

Notez que checkSession() déclenche toutes les règles que vous avez définies, vous devez donc vérifier vos règles dans le Dashboard avant de l’utiliser.

La redirection vers /authorize est effectuée dans unºiframe, et ainsi votre application ne sera pas chargée de nouveau et on ne vous redirigera pas ailleurs.

Cependant, le navigateur doit avoir activé les témoins de tierce-partie. Sinon, checkSession() est incapable d’accéder à la session courante de l’utilisateur (rendant impossible d’obtenir un nouveau jeton sans afficher quelque chose à l’utilisateur). La même chose se produira si les utilisateurs ont activé l’ITP de Safari.

N’oubliez pas d’ajouter l’URL d’où provient la demande d’autorisation à la liste des Origines Web autorisées de votre application Auth0 dans le Dashboard sous les Settings (Paramètres) de votre application.

Dans certains scénarios multi-applications où la déconnexion unique est souhaitée (c’est-à-dire qu’un utilisateur se déconnectant d’une application doit également être déconnecté des autres applications), une application peut être configurée pour interroger périodiquement Auth0 en utilisant checkSession() pour voir si une session existe. Si la session n’existe pas, vous pouvez alors déconnecter l’utilisateur de l’application. La même méthode d’interrogation peut être mise en place pour une authentification silencieuse dans un scénario d’authentification unique (SSO).

L’intervalle d’interrogation entre les vérifications de checkSession() devrait être d’au moins 15 minutes entre chaque appel pour éviter tout problème ultérieur lié à la limite anti-attaques de cet appel.

Si vous essayez de mettre en place une fonctionnalité de réinitialisation du mot de passe, vous utiliserez la méthode changePassword et transmettrez un objet « options », avec un paramètre « connexion » et un paramètre « courriel ».

$('.change_password').click(function () {
    webAuth.changePassword({
      connection: 'db-conn',
      email:   'foo@bar.com'
    }, function (err, resp) {
      if(err){
        console.log(err.message);
      }else{
        console.log(resp);
      }
    });
  });

Management API offre une fonctionnalité qui vous permet de lier et de dissocier des comptes utilisateurs distincts provenant de différents fournisseurs, en les liant à un profil unique (consultez Association de comptes d’utilisateur pour plus de renseignements). Ceci vous permet aussi de mettre à jour les métadonnées utilisateur.

Pour débuter, vous avez d’abord besoin d’un Jeton d’accès à utiliser avec Management API. Pour ce faire, vous pouvez préciser l'audiencehttps://{yourDomain}/api/v2/ lorsque vous initialisez auth0.js, ce qui vous permettra d’obtenir le jeton d’accès du flux d’authentification.

Si vous utilisez des domaines personnalisés, vous devrez instancier une nouvelle copie de webAuth en utilisant votre domaine Auth0 plutôt que votre domaine personnalisé, pour l’utiliser avec les appels de Management API, car elle ne fonctionne qu’avec les domaines Auth0.

var webAuth = new auth0.WebAuth({
  clientID: '{yourClientId}',
  domain: '{yourDomain}',
  redirectUri: 'http://example.com',
  audience: `https://{yourDomain}/api/v2/`,
  scope: 'read:current_user',
  responseType: 'token id_token'
});

Vous pouvez également le faire à l’aide de checkSession() :

webAuth.checkSession(
  {
    audience: `https://{yourDomain}/api/v2/`,
    scope: 'read:current_user'
  }, function(err, result) {
     // use result.accessToken
  }
);

Vous devez spécifier les permissions qui vous sont nécessaires. Vous pouvez demander de suivre les permissions suivantes :

• read:current_user

• update:current_user_identities

• create:current_user_metadata

• update:current_user_metadata

• delete:current_user_metadata

• create:current_user_device_credentials

• delete:current_user_device_credentials

Une fois que vous avez le jeton d’accès, vous pouvez créer une nouvelle instance auth0.Management en le passant par le domaine Auth0 du compte et le jeton d’accès.

var auth0Manage = new auth0.Management({
  domain: '{yourDomain}',
  token: 'ACCESS_TOKEN'
});

Pour obtenir les données du profil utilisateur, utilisez la méthode getUser(), avec le userId et un rappel comme paramètres. La méthode retourne vers le profil utilisateur. Notez que le userID requis ici sera le même que celui récupéré par la méthode client.userInfo. auth0Manage.getUser(userId, cb);

Pour mettre à jour les métadonnées d’un utilisateur, vous devez d’abord créer un objet userMetadata, puis appeler la méthode patchUserMetadata en lui transmettant l’identifiant de l’utilisateur et l’objet userMetadata que vous avez créé. Les valeurs de cet objet vont remplacer les valeurs de la même clé, et en ajouter de nouvelles pour la même clé, encore en ajouter qui n’existent pas encore pour les métadonnées utilisateur. Consultez la documentation sur les métadonnées pour plus de détails sur les métadonnées utilisateur. auth0Manage.patchUserMetadata(userId, userMetadata, cb);

Associer les comptes utilisateur permettra à l’utilisateur de communiquer avec ses comptes et, peu importe lequel ils utilisent, toujours être devant le même profil après connexion. Auth0 traite ces comptes de manière séparée par défaut; si vous souhaitez que les comptes d’un utilisateur soient associées, c’est la seule façon.

La méthode linkUser accepte deux paramètres,userId principal et le jeton d’ID de l’utilisateur secondaire (le jeton obtenu après la connexion avec cette identité). L’ID utilisateur en question est un identifiant unique pour le compte utilisateur primaire. Si vous utilisez cette méthode, l’identifiant doit être transmis avec le préfixe du fournisseur, par exemple auth0|1234567890 ou facebook|1234567890. Consultez Association de comptes d’utilisateur pour plus de renseignements. auth0Manage.linkUser(userId, secondaryUserToken, cb);

Après avoir associé les comptes, un second compte n’existera plus en tant qu’entité séparée au niveau de la base de données utilisateur; il ne sera accessible qu’en tant que partie du compte primaire. Lorsque des comptes sont associés, les métadonnées du compte secondaire ne sont pas fusionnées avec celles du compte principal et, s’ils sont dissociés, le compte secondaire ne conservera pas non plus les métadonnées du compte principal.