Please note, this is a STATIC archive of website developer.mozilla.org from November 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
Persona

Seules cinq étapes sont nécessaires pour installer un système d'authentification Persona sur votre site :

  1. Inclure la bibliothèque JavaScript Persona sur vos pages.
  2. Ajouter les boutons “connexion” et “déconnexion”.
  3. Observer les actions connexion et déconnexion.
  4. Vérifier l'identification de l'utilisateur.
  5. Consulter les meilleures pratiques.

Vous devriez être en mesure de le faire fonctionner en un simple après-midi, mais chaque chose en son temps : si vous comptez utiliser Persona sur votre site, s'il vous plaît, prenez un moment pour vous inscrire sur la liste de diffusion Persona notices. Elle est à faible trafic, étant uniquement utilisée pour annoncer les changements et les problème de sécurité qui pourraient affecter votre site.

Étape 1 : Inclure la bibliothèque Persona

Persona est conçu pour ne pas être lié à un navigateur en particulier et fonctionne bien dans les principaux navigateurs de bureau et mobile.

Dans le futur nous espérons que les navigateurs fourniront un support natif de Persona, mais en attendant nous fournissons une bibliothèque JavaScript qui implémente pleinement l'interface et l'API client du protocole. En incluant cette bibliothèque, vos utilisateurs seront en mesure de se connecter avec Persona, que leur navigateur en ait un support natif ou non.

Une fois la bibliothèque chargée sur la page, les fonctions Persona dont vous avez besoin (watch(), request(), et logout()), seront accessible depuis l'objet global navigator.id.

Pour inclure la bibliothèque JavaScript Persona, vous pouvez placer cette balise  <script> tout en bas de de votre code HTML, avant la fermeture de la balise <body> :

<script src="https://login.persona.org/include.js"></script>

Vous devez inclure ceci dans toutes les pages qui utilisent les fonctions de navigator.id. Persona étant toujours en développement, il est déconseillé d'héberger vous-même une copie du fichier include.js.

Supprimer le Mode de Compatibilité

Vous devez vous assurer que les utilisateurs d'Internet Explorer n'utilisent pas le Mode de Compatibilité, car il cassera Persona.

Vous pouvez soit inclure cette balise <meta>, dans votre page, avant tout élément script :

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Ou vous pouvez définir un entête HTTP sur votre page : X-UA-Compatible: IE=Edge.

Étape 2 : Ajoutez des boutons de connexion et de déconnexion

Persona étant conçu comme une API DOM, vous devez appeler des fonctions quand un utilisateur clique sur un bouton de connexion ou de déconnexion sur votre site. Pour ouvrir la boîte de dialogue Persona et demander à l'utilisateur de se connecter, vous devez appeler navigator.id.request(). Pour la déconnexion, appelez navigator.id.logout(). Notez que l'appel à logout() doit être fait depuis la fonction attachée à l'évènement.

Par exemple :

var signinLink = document.getElementById('signin');
if (signinLink) {
  signinLink.onclick = function() { navigator.id.request(); };
};

var signoutLink = document.getElementById('signout');
if (signoutLink) {
  signoutLink.onclick = function() { navigator.id.logout(); };
};

À quoi devraient ressembler ces boutons ? Consultez notres page de ressources graphiques pour des exemple complets basés sur du CSS !

Étape 3 : Gérez les actions de connexion et de déconnexion

Afin que Persona puisse fonctionner, vous devez lui dire quoi faire lorsqu'un utilisateur se connecte ou se déconnecte. Pour cela, appelez la fonction navigator.id.watch() et passez lui trois paramètres :

  1. L'adresse email de l'utilisateur actuellement connecté à votre site depuis cet ordinateur, ou null si aucun utilisateur n'est connecté. Par exemple, vous pouvez consulter un cookie du navigateur pour déterminer qui est connecté.
  2. Une fonction à appeler lorsqu'une action onlogin est déclenchée. Cette fonction reçoit un seul paramètre, une "assertion d'identité" qui doit être vérifiée.
  3. Une fonction à appeler lorsqu'une action onlogout est déclenchée. Cette fonction ne reçoit aucun paramètre.

Note: Vous devez toujours inclure à la fois onlogin et onlogout lorsque vous appelez navigator.id.watch().

Par exemple, si vous pensez que Bob est connecté à votre site, vous pourriez faire ceci :

var currentUser = '[email protected]';

navigator.id.watch({
  loggedInUser: currentUser,
  onlogin: function(assertion) {
    // Un utilisateur est connecté ! Voici ce qu'il faut faire :
    // 1. Envoyer l'assertion à votre backend pour vérification et pour créer la session.
    // 2. Mettre à jour l'interface utilisateur.
    $.ajax({
      type: 'POST',
      url: '/auth/login', // Ceci est une URL sur votre site web.
      data: {assertion: assertion},
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(xhr, status, err) {
        navigator.id.logout();
        alert("Login failure: " + err);
      }
    });
  },
  onlogout: function() {
    // Un utilisateur s'est déconnecté ! Voici ce qu'il faut faire :
    // Détruire la session de l'utilisateur en redirigeant l'utilisateur ou en appelant votre backend.
    // Assurez vous aussi de réinitialiser loggedInUser à null sur la prochain fois où la page sera chargée
    // (Pas false, ni 0 ou undefined. null)
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // Ceci est une URL sur votre site web.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(xhr, status, err) { alert("Logout failure: " + err); }
    });
  }
});

Dans cet exemple, onlogin et onlogout sont tous deux implémentés en effectuant des requêtes POST asynchrones vers le backend de votre site. Le backend effectue ensuite la connexion ou la déconnexion de l'utilisateur, généralement en créant ou en effaçant des informations dans un cookie de session. Ensuite, si tout fonctionne bien, la page se recharge afin de prendre en compte le nouvel état de connexion.

Notez que si l'assertion ne peut être vérifiée, vous devez appeler navigator.id.logout(), qui indique à Persona qu'aucun utilisateur n'est actuellement connecté. Si vous ne le faîtes pas, alors Persona peut appeler onlogin immédiatement à nouveau, avec la même assertion, et entrainer une boucle infinie d'échecs de connexion.

Bien entendu vous pouvez utiliser des requêtes AJAX pour implémenter cela sans recharger la page ni rediriger l'utilisateur, mais cela ne fait pas partie du périmètre de ce tutoriel.

Voici un autre exemple, cette fois-ci sans utiliser jQuery.

function simpleXhrSentinel(xhr) {
  return function() {
    if (xhr.readyState == 4) {
      if (xhr.status == 200) {
        // recherche la page pour prendre en compte le nouveau statut de connexion
        window.location.reload();
      } else {
        navigator.id.logout();
        alert("XMLHttpRequest error: " + xhr.status); 
      } 
    } 
  };
}

function verifyAssertion(assertion) {
  // Votre backend doit retourner un status code HTTP 200 pour indiquer la bonne
  // vérification de l'adresse e-mail de l'utilisateur et il doit s'arranger pour que
  // currentUser soit bien associer à cette adresse quand la page est rechargée
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "/xhr/sign-in", true);
  // voir https://www.openjs.com/articles/ajax_xmlhttp_using_post.php
  var param = "assertion="+assertion;
  xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  xhr.setRequestHeader("Content-length", param.length);
  xhr.setRequestHeader("Connection", "close");
  xhr.send(param); // pour la vérification par votre backend
  xhr.onreadystatechange = simpleXhrSentinel(xhr);
}

function signoutUser() {
  // Votre backend doit retourner un code statut HTTP 200 pour indique la bonne déconnexion
  // (habituellement après la réinitialisation de plusieurs variables de session)
  // et s'arranger pour que l'association à currentUser soit 'null' quand la page est rechargée
  var xhr = new XMLHttpRequest();
  xhr.open("GET", "/xhr/sign-out", true);
  xhr.send(null);
  xhr.onreadystatechange = simpleXhrSentinel(xhr);
}

// C'est parti !
navigator.id.watch({
  loggedInUser: currentUser,
       onlogin: verifyAssertion,
      onlogout: signoutUser 
}};

Vous devez appeler navigator.id.watch() sur toutes les pages comprenant un bouton de connexion ou de déconnexion. Pour gérer les améliorations de Persona comme la connexion automatique et la déconnexion globale de vos utilisateurs, il est conseillé d'appeler cette fonction sur toutes les pages de votre site.

Persona comparera l'adresse e-mail que vous passez dans loggedInUser avec celle qu'il connaît pour l'utilisateur actuellement connecté. Si elles ne correspondent pas, il peut déclencher automatiquement onlogin ou onlogout au chargement de la page.

Étape 4 : Vérifiez les identifiants de l'utilisateur

Plutôt qu'un mot de passe, Persona utilise des "assertions d'identité" qui sont une sorte de mot de passe à usage unique, lié à un seul site et combiné à l'adresse e-mail de l'utilisateur. Lorsqu'un utilisateur désire se connecter, votre fonction de callback onlogin sera appelée et recevra en paramètre une assertion de cet utilisateur. Avant d'autoriser la connexion, vous devez vérifier la validité de cette assertion.

Il est extrêmement important que vous vérifiiez cette assertion sur votre serveur et non en JavaScript (qui s'exécute dans le navigateur de votre utilisateur) car cela serait trop facile à contourner. L'exemple ci-dessous confie l'assertion au backend du site en utilisant le helper jQuery $.ajax() pour effectuer un POST de celle-ci vers /api/login.

Une fois que le serveur dispose d'une assertion, comment la vérifier ? Le moyen le plus simple est d'utiliser un helper fourni par Mozilla. Effectuez un simple POST de l'assertion vers https://verifier.login.persona.org/verify avec deux paramètres :

  1. assertion: L'assertion d'identité fournie par l'utilisateur.
  2. audience: Le nom de domaine et le port de votre site web. Vous devez coder cette valeur en dur dans votre backend ; ne la composez pas en fonction d'une quelconque donnée fournie par l'utilisateur.

Par exemple, si vous êtes example.com, vous pouvez utiliser la ligne de commande pour tester une assertion avec :

$ curl -d "assertion=<ASSERTION>&audience=https://example.com:443" "https://verifier.login.persona.org/verify"

Si elle est valide, vous recevrez une réponse en JSON comme celle-ci :

{
  "status": "okay",
  "email": "[email protected]",
  "audience": "https://example.com:443",
  "expires": 1308859352261,
  "issuer": "eyedee.me"
}

Pour en apprendre plus à propos du service de vérification, lisez l'API de vérification à distance. Un exemple d'implémentation de /api/login utilisant Python, le framework web Flask, et la librairie HTTP Requests ressemblerait à ça :

@app.route('/api/login', methods=['POST'])
def login():
    # La requête doit avoir une assertion à vérifier
    if 'assertion' not in request.form:
        abort(400)

    # Envoyer l'assertion au service de vérification de Mozilla.
    data = {'assertion': request.form['assertion'], 'audience': 'https://example.com:443'}
    resp = requests.post('https://verifier.login.persona.org/verify', data=data)

    # Le vérificateur a-t-il répondu ?
    if resp.ok:
        # Décoder la réponse
        verification_data = json.loads(resp.content)

        # Si l'assertion est valide
        if verification_data['status'] == 'okay':
            # Connecter l'utilisateur en lui envoyant un cookie de session sécurisé
            session.update({'email': verification_data['email']})
            return resp.content

    # Oups, quelque chose a échoué. Abandon.
    abort(500)

La gestion de session est probablement très similaire à votre système de connexion existant. Le premier grand changement est de vérifier l'identité de l'utilisateur en vérifiant une assertion plutôt que son mot de passe. L'autre grand changement est de s'assurer que l'adresse email de l'utilisateur est disponible pour la passer dans le paramètre loggedInEmail de navigator.id.watch().

La déconnexion est simple : vous n'avez qu'à effacer le cookie de session de l'utilisateur.

Étape 5 : Consultez les bonnes pratiques

Une fois que tout fonctionne et que vous vous êtez connecté et déconnecté avec succès de votre site, vous devriez prendre un moment pour consulter les bonnes pratiques pour utiliser Persona de manière sûre et sécurisée.

Si vous construisez un site de production, consulter le guide de l'implémenteur, où nous collections les astuces pour intégrer les fonctionnalités souvent requises dans les systèmes de connexion.

Enfin, n'oubliez pas de vous inscrire à la liste de difussion Persona notices afin d'être informé des failles de sécurité ou de changements incompatibles avec de précédentes versions de l'API Persona. Cette liste a un taffic extrêmement faible : elle est uniquement utilisée pour annoncer des changements qui pourraient avoir un impact négatif sur votre site.

 

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : alexisdelee, Sulice, EtienneMallard, wordsbybird, tregagnon, JonathanMM, matteodelabre, Derek, regisg27, Goofy, Jeremie, dooggie, Malika
 Dernière mise à jour par : alexisdelee,