Révision 348837 sur Configuration rapide

  • Raccourci de la révision : Persona/Quick_Setup
  • Titre de la révision : Quick Setup
  • ID de la révision : 348837
  • Créé :
  • Créateur : Derek
  • Version actuelle ? Non
  • Commentaire
Étiquettes : 

Contenu de la révision

Cette page a besoin d'être traduite. Votre aide est la bienvenue

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

  1. Inclure la librairie 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 changemments et les problème de sécurité qui pourraient affecter votre site.

Première étape : Inclure la librairie Persona

Persona est conçu pour ne pas être lié à un navigateur en particulier et fonctionne bien dans tous les navigateurs de bureau et mobiles. Ceci est possible grâce à la librairie JavaScript multi-plateformes Persona. Une fois cette librairie chargée dans votre page, les fonctions Persona dont vous aurez besoin ({{ domxref("navigator.id.watch()", "watch()") }}, {{ domxref("navigator.id.request()", "request()") }}, et {{ domxref("navigator.id.logout()", "logout()") }}) seront disponibles dans l'objet global navigator.id.

Pour inclure la librairie JavaScript Persona, vous pouvez placer cette balise  script dans l'entête de vos pages :

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

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

Etape 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 {{ domxref("navigator.id.request()") }}. Pour la déconnexion, appelez {{ domxref("navigator.id.logout()") }}.

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 !

Step 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 {{ domxref("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 {{ domxref("navigator.id.watch()") }}.

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

var currentUser = 'bob@example.com';

navigator.id.watch({
  loggedInEmail: currentUser,
  onlogin: function(assertion) {
    // A user has logged in! Here you need to:
    // 1. Send the assertion to your backend for verification and to create a session.
    // 2. Update your UI.
    $.ajax({
      type: 'POST',
      url: '/auth/login', // This is a URL on your website.
      data: {assertion: assertion},
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("login failure" + res); }
    });
  },
  onlogout: function() {
    // A user has logged out! Here you need to:
    // Tear down the user's session by redirecting the user or making a call to your backend.
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // This is a URL on your website.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("logout failure" + res); }
    });
  }
});

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.

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.

 

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.

Step 4: Verify the user’s credentials

Instead of passwords, Persona uses “identity assertions,” which are kind of like single-use, single-site passwords combined with the user’s email address. When a user wants to log in, your onlogin callback will be invoked with an assertion from that user. Before you can log them in, you must verify that the assertion is valid.

It’s extremely important that you verify the assertion on your server, and not in JavaScript running on the user’s browser, since that would be easy to forge. The example above handed off the assertion to the site’s backend by using jQuery’s $.ajax() helper to POST it to /api/login.

Once your server has an assertion, how do you verify it? The easiest way is to use a helper service provided by Mozilla. Simply POST the assertion to https://verifier.login.persona.org/verify with two parameters:

  1. assertion: The identity assertion provided by the user.
  2. audience: The hostname and port of your website. You must hardcode this value in your backend; do not derive it from any data supplied by the user.

For example, if you’re example.com, you can use the command line to test an assertion with:

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

If it’s valid, you’ll get a JSON response like this:

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

You can learn more about the verification service by reading The Verification Service API. An example /api/login implementation, using Python, the Flask web framework, and the Requests HTTP library might look like this:

@app.route('/api/login', methods=['POST'])
def login():
    # The request has to have an assertion for us to verify
    if 'assertion' not in request.form:
        abort(400)

    # Send the assertion to Mozilla's verifier service.
    data = {'assertion': request.form['assertion'], 'audience': 'https://example.com:443'}
    resp = requests.post('https://verifier.login.persona.org/verify', data=data)

    # Did the verifier respond?
    if resp.ok:
        # Parse the response
        verification_data = json.loads(resp.content)

        # Check if the assertion was valid
        if verification_data['status'] == 'okay':
            # Log the user in by setting a secure session cookie
            session.update({'email': verification_data['email']})
            return resp.content

    # Oops, something failed. Abort.
    abort(500)

The session management is probably very similar to your existing login system. The first big change is in verifying the user’s identity by checking an assertion instead of checking a password. The other big change is ensuring that the user’s email address is available for use as the loggedInEmail parameter to {{ domxref("navigator.id.watch()") }}.

Logout is simple: you just need to remove the user’s session cookie.

Step 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, vous devriez écrire des tests d'intégration qui simulent la connexion et la déconnexion d'un utilisateur à votre site en utilisant BrowserID. Pour faciliter ces actions dans Selenium, nous vous conseillons la librairie bidpom. Les sites mockmyid.com et personatestuser.org peuvent également s'avérer utiles.

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.

 

Source de la révision

<div class="warning">
  Cette page a besoin d'être traduite. Votre aide est la bienvenue</div>
<p>Seules cinq étapes sont nécessaires pour installer un système d'authentification Persona sur votre site :</p>
<ol>
  <li>Inclure la librairie javascript Persona sur vos pages.</li>
  <li>Ajouter les boutons “connexion” et “déconnexion”.</li>
  <li>Observer les actions connexion et déconnexion.</li>
  <li>Vérifier l'identification de l'utilisateur.</li>
  <li>Consulter les meilleures pratiques.</li>
</ol>
<p>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&nbsp;<a href="https://mail.mozilla.org/listinfo/persona-notices">Persona notices</a>. Elle est à faible trafic, étant uniquement utilisée pour annoncer les changemments et les problème de sécurité qui pourraient affecter votre site.</p>
<h2 id="Premi.C3.A8re_.C3.A9tape_.3A_Inclure_la_librairie_Persona">Première étape : Inclure la librairie Persona</h2>
<p>Persona est conçu pour ne pas être lié à un navigateur en particulier et fonctionne bien dans <a href="https://developer.mozilla.org/docs/persona/Browser_compatibility">tous les navigateurs de bureau et mobiles</a>. Ceci est possible grâce à la librairie JavaScript multi-plateformes Persona. Une fois cette librairie chargée dans votre page, les fonctions Persona dont vous aurez besoin ({{ domxref("navigator.id.watch()", "watch()") }}, {{ domxref("navigator.id.request()", "request()") }}, et {{ domxref("navigator.id.logout()", "logout()") }}) seront disponibles dans l'objet global&nbsp;<code>navigator.id</code>.</p>
<p>Pour inclure la librairie JavaScript Persona, vous pouvez placer cette balise &nbsp;<code>script</code> dans l'entête de vos pages :</p>
<pre class="brush: html;">
&lt;script src="https://login.persona.org/include.js"&gt;&lt;/script&gt;
</pre>
<p>Vous <strong>devez</strong> inclure ceci dans toutes les pages qui utilisent les fonctions de&nbsp;{{ domxref("navigator.id") }}. Persona étant toujours en développement, il est déconseillé d'héberger vous-même une copie du fichier&nbsp;<code>include.js</code>.</p>
<h2 id="Etape_2.3A_Ajoutez_des_boutons_de_connexion_et_de_d.C3.A9connexion">Etape 2: Ajoutez des boutons de connexion et de déconnexion</h2>
<p>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 {{ domxref("navigator.id.request()") }}. Pour la déconnexion, appelez {{ domxref("navigator.id.logout()") }}.</p>
<p>Par exemple :</p>
<pre class="brush: js;">
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(); };
};
</pre>
<p>À quoi devraient ressembler ces boutons ? Consultez notres page de&nbsp;<a href="https://developer.mozilla.org/docs/persona/branding">ressources graphiques</a>&nbsp;pour des exemple complets basés sur du CSS !</p>
<h2 id="Step_3.3A_Watch_for_login_and_logout_actions">Step 3: Gérez les actions de connexion et de déconnexion</h2>
<p>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 {{ domxref("navigator.id.watch()") }} et passez lui trois paramètres :</p>
<ol>
  <li>
    <p>L'adresse email de l'utilisateur actuellement connecté à votre site depuis cet ordinateur, ou <code>null</code> si aucun utilisateur n'est connecté. Par exemple, vous pouvez consulter un cookie du navigateur pour déterminer qui est connecté.</p>
  </li>
  <li>
    <p>Une fonction à appeler lorsqu'une action&nbsp;<code>onlogin</code> est déclenchée. Cette fonction reçoit un seul paramètre, une "assertion d'identité" qui doit être vérifiée.</p>
  </li>
  <li>
    <p>Une fonction à appeler lorsqu'une action&nbsp;<code>onlogout</code> est déclenchée. Cette fonction ne reçoit aucun paramètre.</p>
  </li>
</ol>
<div class="note style-wrap">
  <p><strong>Note:</strong>&nbsp;Vous devez toujours inclure à la fois&nbsp;<code>onlogin</code> et&nbsp;<code>onlogout</code>&nbsp;lorsque vous appelez {{ domxref("navigator.id.watch()") }}.</p>
</div>
<p>Par exemple, si vous pensez que Bob est connecté à votre site, vous pourriez faire ceci :</p>
<pre class="brush: js;">
var currentUser = 'bob@example.com';

navigator.id.watch({
  loggedInEmail: currentUser,
  onlogin: function(assertion) {
    // A user has logged in! Here you need to:
    // 1. Send the assertion to your backend for verification and to create a session.
    // 2. Update your UI.
    $.ajax({
      type: 'POST',
      url: '/auth/login', // This is a URL on your website.
      data: {assertion: assertion},
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("login failure" + res); }
    });
  },
  onlogout: function() {
    // A user has logged out! Here you need to:
    // Tear down the user's session by redirecting the user or making a call to your backend.
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // This is a URL on your website.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("logout failure" + res); }
    });
  }
});
</pre>
<p>Dans cet exemple,&nbsp;<code>onlogin</code>&nbsp;et&nbsp;<code>onlogout</code>&nbsp;sont tous deux implémentés en effectuant des requêtes&nbsp;<code>POST</code>&nbsp;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.</p>
<p>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.</p>
<p>Voici un autre exemple, cette fois-ci sans utiliser jQuery.</p>
<p>&nbsp;</p>
<p>Vous <strong>devez</strong> 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, <strong>il est conseillé</strong>&nbsp;d'appeler cette fonction sur toutes les pages de votre site.</p>
<h2 id="Step_4.3A_Verify_the_user.E2.80.99s_credentials">Step 4: Verify the user’s credentials</h2>
<p>Instead of passwords, Persona uses “identity assertions,” which are kind of like single-use, single-site passwords combined with the user’s email address. When a user wants to log in, your <code>onlogin</code> callback will be invoked with an assertion from that user. Before you can log them in, you must verify that the assertion is valid.</p>
<p>It’s <em>extremely important</em> that you verify the assertion on your server, and not in JavaScript running on the user’s browser, since that would be easy to forge. The example above handed off the assertion to the site’s backend by using jQuery’s <code>$.ajax()</code> helper to <code>POST</code> it to <code>/api/login</code>.</p>
<p>Once your server has an assertion, how do you verify it? The easiest way is to use a helper service provided by Mozilla. Simply <code>POST</code> the assertion to <code>https://verifier.login.persona.org/verify</code> with two parameters:</p>
<ol>
  <li><code>assertion</code>: The identity assertion provided by the user.</li>
  <li><code>audience</code>: The hostname and port of your website. You must hardcode this value in your backend; do not derive it from any data supplied by the user.</li>
</ol>
<p>For example, if you’re <code>example.com</code>, you can use the command line to test an assertion with:</p>
<pre class="brush: bash;">
$ curl -d "assertion=&lt;ASSERTION&gt;&amp;audience=https://example.com:443" "https://verifier.login.persona.org/verify"
</pre>
<p>If it’s valid, you’ll get a JSON response like this:</p>
<pre class="brush: js;">
{
  "status": "okay",
  "email": "bob@eyedee.me",
  "audience": "https://example.com:443",
  "expires": 1308859352261,
  "issuer": "eyedee.me"
}
</pre>
<p>You can learn more about the verification service by reading <a href="https://developer.mozilla.org/en-US/docs/BrowserID/Remote_Verification_API">The Verification Service API</a>. An example <code>/api/login</code> implementation, using <a href="http://python.org/">Python</a>, the <a href="http://flask.pocoo.org/">Flask</a> web framework, and the <a href="http://python-requests.org">Requests</a> HTTP library might look like this:</p>
<pre class="brush: python;">
@app.route('/api/login', methods=['POST'])
def login():
    # The request has to have an assertion for us to verify
    if 'assertion' not in request.form:
        abort(400)

    # Send the assertion to Mozilla's verifier service.
    data = {'assertion': request.form['assertion'], 'audience': 'https://example.com:443'}
    resp = requests.post('https://verifier.login.persona.org/verify', data=data)

    # Did the verifier respond?
    if resp.ok:
        # Parse the response
        verification_data = json.loads(resp.content)

        # Check if the assertion was valid
        if verification_data['status'] == 'okay':
            # Log the user in by setting a secure session cookie
            session.update({'email': verification_data['email']})
            return resp.content

    # Oops, something failed. Abort.
    abort(500)
</pre>
<p>The session management is probably very similar to your existing login system. The first big change is in verifying the user’s identity by checking an assertion instead of checking a password. The other big change is ensuring that the user’s email address is available for use as the <code>loggedInEmail</code> parameter to {{ domxref("navigator.id.watch()") }}.</p>
<p>Logout is simple: you just need to remove the user’s session cookie.</p>
<h2 id="Step_5.3A_Review_best_practices">Step 5: Consultez les bonnes pratiques</h2>
<p>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 <a href="https://developer.mozilla.org/docs/BrowserID/Security_Considerations">bonnes pratiques</a>&nbsp;pour utiliser Persona de manière sûre et sécurisée.</p>
<p>Si vous construisez un site de production, vous devriez écrire des tests d'intégration qui simulent la connexion et la déconnexion d'un utilisateur à votre site en utilisant BrowserID. Pour faciliter ces actions dans Selenium, nous vous conseillons la librairie&nbsp;<a href="https://github.com/mozilla/bidpom" title="https://github.com/mozilla/bidpom">bidpom</a>. Les sites <a href="https://mockmyid.com/" title="https://mockmyid.com/">mockmyid.com</a>&nbsp;et&nbsp;<a href="http://personatestuser.org" title="http://personatestuser.org">personatestuser.org</a> peuvent également s'avérer utiles.</p>
<p>Enfin, n'oubliez pas de vous inscrire à la<span style="line-height: inherit;">&nbsp;liste de difussion&nbsp;</span><a href="https://mail.mozilla.org/listinfo/persona-notices" style="line-height: inherit;">Persona notices</a><span style="line-height: inherit;"> 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.</span></p>
<p>&nbsp;</p>
Revenir à cette révision