Référence de l’API Lock

Détails sur l’API Lock v11.

Lock offre de nombreuses méthodes, fonctionnalités et options configurables. Cette référence est conçue pour vous guider vers celles dont vous avez besoin et vous expliquer comment les utiliser. Cliquez ci-dessous pour accéder directement à la méthode recherchée, ou parcourez simplement la liste! Si vous cherchez de l’information sur les événements émis par Lock, ils sont répertoriés dans la section de la méthode on()!

• new Auth0Lock - Instancier Lock
• getUserInfo() - Obtenir le profil d’un utilisateur connecté
• show() - Afficher le widget Lock
• on() - Écouter les événements
• resumeAuth() - À utiliser pour terminer le flux d’authentification lorsque autoParseHash est faux
• checkSession() - Obtenir un nouveau token d’Auth0 pour un utilisateur authentifié
• logout() - Déconnecter l’utilisateur

Auth0Lock

new Auth0Lock(clientID, domain, options)

Initialise une nouvelle instance de Auth0Lock configurée avec le clientID de votre application et le domain de votre compte dans votre Dashboard Auth0. Le troisième paramètre, facultatif, est un objet options utilisé pour configurer Lock selon les besoins de votre application. Vous trouverez cette information dans les paramètres de l’application.

• clientId {String} : Paramètre requis. Le clientId de votre application dans Auth0.
• domain {String} : Paramètre requis. Votre domaine Auth0, généralement your-account.auth0.com.
• options {Object} : Paramètre facultatif. Permet de configurer l’apparence et le comportement de Lock. Consultez la page des options de configuration pour en savoir plus.

getUserInfo()

getUserInfo(accessToken, callback)

Une fois que l’utilisateur s’est connecté et que vous avez un token en main, vous pouvez utiliser ce token pour obtenir le profil de l’utilisateur avec getUserInfo. Cette méthode remplace la méthode getProfile(), désormais obsolète.

• accessToken {String}: Token de l’utilisateur.
• callback {Function}: Sera appelée une fois le profil de l’utilisateur récupéré.

lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    alert("hello " + profile.name);
  }
});

show()

show(options)

La méthode show affiche le widget. À partir de la version 10.2.0 de Lock, la méthode show peut désormais accepter un objet options comme paramètre. Notez que ce paramètre sert à remplacer les options de votre Lock pour cet affichage précis du widget — les options devraient être définies au moment d’instancier Lock, puis remplacées ici seulement au besoin, selon votre cas d’utilisation.

Le sous-ensemble suivant d’options peut remplacer les valeurs attribuées (ou les valeurs par défaut) lors de l’instanciation de Lock :

• allowedConnections
• auth.params
• allowLogin
• allowSignUp
• allowForgotPassword
• initialScreen
• rememberLastLogin

Pour en savoir plus sur la liste complète des options configurables pouvant être choisies au moment d’instancier Lock, par opposition au sous-ensemble limité ci-dessus qui peut être remplacé dans la méthode show, consultez la page des options configurables par l’utilisateur.

Exemples de remplacement d’options :

// Afficher le widget Lock sans remplacer aucune option
lock.show();

// Afficher le widget Lock en remplaçant certaines options
lock.show({
  allowedConnections: ["twitter", "facebook"],
  allowSignUp: false
});

Les options doivent être définies lors de la première initialisation de Lock var lock = new Auth0Lock(clientId, domain, options);. Les options ne doivent être passées à show que pour remplacer celles que vous avez déjà définies au moment d’afficher le widget à cet endroit précis.

Il existe aussi une option supplémentaire qui peut être définie dans la méthode show, appelée flashMessage.

message flash

Cet objet est offert uniquement comme option pour la méthode show, et non dans l’objet options habituel lors de l’instanciation de Lock. L’objet flashMessage affiche un message flash d’erreur ou de réussite lorsque Lock s’affiche. Il comporte les paramètres suivants :

• type {String}: Le type de message; il doit être soit error, soit success.
• text {String}: Le texte à afficher.

lock.show({
  flashMessage:{
    type: 'success',
    text: 'Amazing Success!!'
  }
});

Une utilisation pratique de l’option flashMessage consiste à gérer les erreurs d’autorisation. Le flashMessage peut contenir le texte descriptif de l’erreur.

lock.on('authorization_error', function(error) {
  lock.show({
    flashMessage: {
      type: 'error',
      text: error.errorDescription
    }
  });
});

Donc, si [e-mail] tentait maintenant de se connecter alors qu’il s’agit d’un utilisateur bloqué, Lock s’afficherait de nouveau, avec une barre supérieure affichant le message d’erreur, au lieu que la connexion échoue simplement et que Lock se ferme.

hide()

hide()

La méthode hide ferme le widget s’il est ouvert. Comme le widget se ferme de lui-même dans la plupart des cas, cette méthode n’est généralement utilisée que dans certains cas d’utilisation précis. Par exemple, on peut vouloir écouter l’événement unrecoverable_error, puis hide Lock et rediriger l’utilisateur vers une page d’erreur personnalisée. Autre exemple : les utilisateurs qui implémentent le mode popup peuvent devoir hide manuellement le widget après le déclenchement de l’événement authenticated.

Exemple d’utilisation pour masquer (fermer) le widget Lock en mode popup :

// Écouter l'événement authenticated et masquer Lock
lock.on("authenticated", function() {
  lock.hide();

  // Tout autre traitement à effectuer lors de l'événement authenticated

});

on()

Lock émet des événements tout au long de son cycle de vie. La méthode on peut être utilisée pour écouter certains événements et y réagir.

• show : émis lorsque Lock est affiché. N’a aucun argument.
• hide : émis lorsque Lock est masqué. N’a aucun argument.
• unrecoverable_error : émis lorsqu’une erreur irrécupérable survient, par exemple lorsqu’aucune connexion n’est disponible. Contient l’erreur comme seul argument.
• authenticated : émis après une authentification réussie. Contient le résultat de l’authentification comme seul argument. Le résultat de l’authentification contient le token qui peut être utilisé pour obtenir le profil de l’utilisateur ou être stocké pour ouvrir une session lors de vérifications ultérieures.
• authorization_error : émis lorsqu’une autorisation échoue. Contient l’erreur comme seul argument.
• hash_parsed : chaque fois qu’un nouvel objet Auth0Lock est initialisé en mode de redirection (par défaut), il tente d’analyser la partie hachage de l’URL pour y trouver le résultat d’une tentative de login. Il s’agit d’un événement de bas niveau destiné à des cas d’utilisation avancés, et authenticated ainsi que authorization_error devraient être privilégiés lorsque possible. Ensuite, cet événement sera émis avec null s’il n’a rien trouvé dans le hachage. Il sera émis avec le même argument que l’événement authenticated après un login réussi, ou avec le même argument que authorization_error si quelque chose s’est mal passé. Cet événement ne sera pas émis en mode popup, car il n’est alors pas nécessaire d’analyser la partie hachage de l’URL.
• forgot_password ready : émis lorsque l’écran “mot de passe oublié” est affiché. (Seulement dans la version >10.18)
• forgot_password submit : émis lorsque l’utilisateur clique sur le bouton de soumission de l’écran “mot de passe oublié”. (Seulement dans la version >10.14)
• signin ready : émis lorsque l’écran “Sign in” est affiché.
• signup ready : émis lorsque l’écran “Sign up” est affiché.
• signin submit : émis lorsque l’utilisateur clique sur le bouton de soumission de l’écran “Login”. (Seulement dans la version >10.18)
• signup submit : émis lorsque l’utilisateur clique sur le bouton de soumission de l’écran “Sign Up”. (Seulement dans la version >10.18)
• federated login : émis lorsque l’utilisateur clique sur un bouton de connexion sociale. Contient le nom de la connexion et la stratégie comme arguments. (Seulement dans la version >10.18)
• socialOrPhoneNumber ready : émis lorsque l’écran Passwordless avec Social + numéro de téléphone est affiché
• socialOrPhoneNumber submit : émis lorsque l’écran Passwordless avec Social + numéro de téléphone est soumis
• socialOrEmail ready : émis lorsque l’écran Passwordless avec Social + Email est affiché
• socialOrEmail submit : émis lorsque l’écran Passwordless avec Social + Email est soumis
• vcode ready : émis lorsque l’écran Passwordless avec le mot de passe à usage unique est affiché
• vcode submit : émis lorsque l’écran Passwordless avec le mot de passe à usage unique est soumis

L’écouteur de l’événement authenticated reçoit un seul argument, un objet authResult. Cet objet contient les propriétés suivantes : accessToken, idToken, state, refreshToken et idTokenPayload.

Voici un exemple d’utilisation de l’événement authenticated :

resumeAuth()

Cette méthode ne peut être utilisée que si vous définissez l’option auth.autoParseHash à false. Vous devrez appeler resumeAuth pour terminer le flux d’authentification. Cette méthode est utile si vous utilisez un routeur côté client qui se sert d’un # pour gérer les URL (angular2 avec useHash ou react-router avec hashHistory).

• hash {String} : Le fragment de hachage reçu lors de la redirection.
• callback {Function} : Sera invoqué une fois l’analyse terminée. Reçoit une erreur (s’il y en a une) comme premier argument et le résultat de l’authentification comme deuxième. S’il n’y a aucun hachage disponible, les deux arguments seront null.

lock.resumeAuth(hash, function(error, authResult) {
  if (error) {
    alert("Could not parse hash");
  }
  //Ceci est un exemple seulement ; vous ne devriez pas journaliser les jetons d'accès en production.
  console.log(authResult.accessToken);
});

checkSession()

La méthode checkSession vous permet d’obtenir un nouveau token auprès d’Auth0 pour un utilisateur déjà authentifié auprès d’Auth0 pour votre domaine. Elle accepte les paramètres suivants :

• options {object}: Facultatif. Accepte tout paramètre OAuth2 valide qui serait normalement envoyé à /authorize. Si vous les omettez, elle utilisera ceux fournis lors de l’initialisation d’Auth0.
• callback {Function}: Sera appelée avec le résultat du renouvellement du token. Prend une erreur (s’il y a lieu) comme premier argument et le résultat de l’authentification comme second.

lock.checkSession({}, function(err, authResult) {
  // gérer l'erreur ou les nouveaux jetons
});

logout()

Déconnecte l’utilisateur.

• options {objet}: Ce paramètre est facultatif et suit les mêmes règles que auth0.js logout().

lock.logout({
  returnTo: 'https://myapp.com/bye-bye'
});