Configuration rapide

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

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: Watch for login and logout actions

For Persona to function, you need to tell it what to do when a user logs in or out. This is done by calling the {{ domxref("navigator.id.watch()") }} function and supplying three parameters:

  1. The loggedInEmail of your site’s current user, or null if none. You should generate this dynamically when you render a page.

  2. A function to invoke when an onlogin action is triggered. This function is passed a single parameter, an “identity assertion,” which must be verified.

  3. A function to invoke when an onlogout action is triggered. This function is not passed any parameters.

Note: You must always include both onlogin and onlogout when you call {{ domxref("navigator.id.watch()") }}.

For example, if you currently think Bob is logged into your site, you might do this:

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

In this example, both onlogin and onlogout are implemented by making an asynchronous POST request to your site’s backend. The backend then logs the user in or out, usually by setting or deleting information in a session cookie. Then, if everything checks out, the page reloads to take into account the new login state.

You can, of course, use AJAX to implement this without reloading or redirecting, but that’s beyond the scope of this tutorial.

You must call this function on every page with a login or logout button. To support Persona enhancements like automatic login and global logout for your users, you should call this function on every page of your 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: Review best practices

Once everything works and you’ve successfully logged into and out of your site, you should take a moment to review best practices for using Persona safely and securely.

If you're making a production-ready site, you may want to write integration tests that simulate logging a user in and out of your site using BrowserID. To facilitate this action in Selenium, consider using the bidpom library. The sites mockmyid.com and personatestuser.org may also be helpful.

Lastly, don’t forget to sign up for the Persona notices mailing list so you’re notified of any security issues or backwards incompatible changes to the Persona API. The list is extremely low traffic: it’s only used to announce changes which may adversely impact your 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="Step_2.3A_Add_login_and_logout_buttons">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: Watch for login and logout actions</h2>
<p>For Persona to function, you need to tell it what to do when a user logs in or out. This is done by calling the {{ domxref("navigator.id.watch()") }} function and supplying three parameters:</p>
<ol>
  <li>
    <p>The <code>loggedInEmail</code> of your site’s current user, or <code>null</code> if none. You should generate this dynamically when you render a page.</p>
  </li>
  <li>
    <p>A function to invoke when an <code>onlogin</code> action is triggered. This function is passed a single parameter, an “identity assertion,” which must be verified.</p>
  </li>
  <li>
    <p>A function to invoke when an <code>onlogout</code> action is triggered. This function is not passed any parameters.</p>
  </li>
</ol>
<div class="note style-wrap">
  <p><strong>Note:</strong> You must always include both <code>onlogin</code> and <code>onlogout</code> when you call {{ domxref("navigator.id.watch()") }}.</p>
</div>
<p>For example, if you currently think Bob is logged into your site, you might do this:</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>In this example, both <code>onlogin</code> and <code>onlogout</code> are implemented by making an asynchronous <code>POST</code> request to your site’s backend. The backend then logs the user in or out, usually by setting or deleting information in a session cookie. Then, if everything checks out, the page reloads to take into account the new login state.</p>
<p>You can, of course, use AJAX to implement this without reloading or redirecting, but that’s beyond the scope of this tutorial.</p>
<p>You <strong>must</strong> call this function on every page with a login or logout button. To support Persona enhancements like automatic login and global logout for your users, you <strong>should</strong> call this function on every page of your 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: Review best practices</h2>
<p>Once everything works and you’ve successfully logged into and out of your site, you should take a moment to review <a href="https://developer.mozilla.org/docs/BrowserID/Security_Considerations">best practices</a> for using Persona safely and securely.</p>
<p>If you're making a production-ready site, you may want to write integration tests that simulate logging a user in and out of your site using BrowserID. To facilitate this action in Selenium, consider using the <a href="https://github.com/mozilla/bidpom" title="https://github.com/mozilla/bidpom">bidpom</a> library. The sites <a href="https://mockmyid.com/" title="https://mockmyid.com/">mockmyid.com</a> and <a href="http://personatestuser.org" title="http://personatestuser.org">personatestuser.org</a> may also be helpful.</p>
<p>Lastly, don’t forget to sign up for the <a href="https://mail.mozilla.org/listinfo/persona-notices">Persona notices</a> mailing list so you’re notified of any security issues or backwards incompatible changes to the Persona API. The list is extremely low traffic: it’s only used to announce changes which may adversely impact your site.</p>
<p>&nbsp;</p>
Revenir à cette révision