API de vérification

  • Raccourci de la révision : Persona/API_de_verification
  • Titre de la révision : API de vérification
  • ID de la révision : 446419
  • Créé :
  • Créateur : Delapouite
  • Version actuelle ? Non
  • Commentaire fixed title and added Persona tag

Contenu de la révision

Résumé

Lorsqu'un utilisateur essaie de se connecter sur un site, son navigateur génère un objet de données appelé une assertion. Il s'agit essentiellement d'une adresse mail cryptée. Le navigateur envoie cette assertion au site, qui doit vérifier sa validité avant de connecter l'utilisateur.

Les assertions peuvent être vérifiées localement, ou en utilisant l'API disponible à l'adresse https://verifier.login.persona.org/verify. Cette page décrit comment utiliser l'API.

Méthode

Envoyez une requête HTTP POST à l'adresse https://verifier.login.persona.org/verify.

Paramètres

assertion
L'assertion est fournie par l'utilisateur. Disponible en tant que premier paramètre passé à la fonction onlogin dans {{ domxref("navigator.id.watch()") }}.
audience
Le protocole, nom de domaine et port de votre site. Par exemple : "https://example.com:443".

Valeurs de retour

La requête retourne un objet JSON contenant une propriété status qui peut valoir "okay" ou "failure". En fonction de ces valeurs, l'objet peut contenir des éléments additionels listés ci-dessous.

"okay"

L'assertion est valide.

Dans ce cas, l'objet JSON contient en plus les propriétés suivantes :

"email" L'adresse mail contenue dans l'assertion, pour permettre la connexion de l'utilisateur.
"audience" La valeur audience contenue dans l'assertion. Doit être l'URL de votre propre site.
"expires" La date à laquelle expire l'assertion, exprimée The date the assertion expires, expressed as the primitive value of a Date object qui est le nombre de secondes écoulées depuis le 1er Janvier 1970 00h00 GMT.
"issuer" Le nom du fournisseur d'identité ayant fourni l'assertion.

"failure"

L'assertion n'est pas valide.

Dans ce cas, l'objet JSON contient une propriété additionnelle :

"reason" Une chaîne de caractère expliquant pourquoi la validation de l'assertion a échoué

Exemples

node.js

Cet exemple utilise un serveur node.js utilisant express.js

var express = require("express"),
    app = express.createServer(),
    https = require("https"),
    querystring = require("querystring");
/* ... */

// La variable audience doit correspondre à ce qu'affiche la barre d'adresse du navigateur,
// ce qui inclut le protocole, le nom de domaine et le port
var audience = "http://localhost:8888";

app.post("/authenticate", function(req, res) {
  var vreq = https.request({
    host: "verifier.login.persona.org",
    path: "/verify",
    method: "POST"
  }, function(vres) {
    var body = "";
    vres.on('data', function(chunk) { body+=chunk; } )
        .on('end', function() {
          try {
            var verifierResp = JSON.parse(body);
            var valid = verifierResp && verifierResp.status === "okay";
            var email = valid ? verifierResp.email : null;
            req.session.email = email;
            if (valid) {
              console.log("l'assertion a été vérifiée avec succès pour le mail :", email);
              res.json(email);
            } else {
              console.log("l'assertion n'a pas été validée pour la raison suivante :", verifierResp.reason);
              res.send(verifierResp.reason, 403);
            }
          } catch(e) {
            console.log("le verifier n'a pas renvoyé un objet JSON");
            // bogus response from verifier!
            res.send("bogue de la part du verifier !", 403);

          }
        });
  });

  vreq.setHeader('Content-Type', 'application/x-www-form-urlencoded');

  var data = querystring.stringify({
    assertion: req.body.assertion,
    audience: audience
  });

  vreq.setHeader('Content-Length', data.length);
  vreq.write(data);
  vreq.end();

  console.log("vérification de l'assertion");
});

via Lloyd Hilaiel

PHP

$url = 'https://verifier.login.persona.org/verify';
$assert = filter_input(
    INPUT_POST,
    'assertion',
    FILTER_UNSAFE_RAW,
    FILTER_FLAG_STRIP_LOW|FILTER_FLAG_STRIP_HIGH
);
//utiliser la superglobale $_POST pour PHP < 5.2 et écrire votre propre filtre 
$params = 'assertion=' . urlencode($assert) . '&audience=' .
           urlencode('http://example.com:80');
$ch = curl_init();
$options = array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_POST => 2,
    CURLOPT_POSTFIELDS => $params
);
curl_setopt_array($ch, $options);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Via Christian Heilmann

Note: si vous envoyez les paramètres assertion et audience en tant qu'objet JSON, ils ne doivent pas être encodés. S'ils sont envoyés en tant que paramètres normaux d'une requête HTTP POST, comme dans l'exemple ci-dessus, ils doivent être encodés.

Source de la révision

<h2 id="Summary" name="Summary">Résumé</h2>
<p>Lorsqu'un utilisateur essaie de se connecter sur un site, son navigateur génère un objet de données appelé une <em>assertion</em>. Il s'agit essentiellement d'une adresse mail cryptée. Le navigateur envoie cette assertion au site, qui doit vérifier sa validité avant de connecter l'utilisateur.</p>
<p>Les assertions peuvent être vérifiées localement, ou en utilisant l'API disponible à l'adresse&nbsp;<span class="link-https"><code>https://verifier.login.persona.org/verify</code></span>. Cette page décrit comment utiliser l'API.</p>
<h2 id="Methods" name="Methods">Méthode</h2>
<p>Envoyez une requête HTTP POST à l'adresse <code>https://verifier.login.persona.org/verify</code>.</p>
<h3 id="Parameters" name="Parameters">Paramètres</h3>
<dl>
  <dt>
    <code>assertion</code></dt>
  <dd>
    L'assertion est fournie par l'utilisateur. Disponible en tant que premier paramètre passé à la fonction <code>onlogin</code>&nbsp;dans {{ domxref("navigator.id.watch()") }}.</dd>
  <dt>
    <code>audience</code></dt>
  <dd>
    Le protocole, nom de domaine et port de votre site. Par exemple : "<code>https://example.com:443</code>".</dd>
</dl>
<h3 id="Return_values" name="Return_values">Valeurs de retour</h3>
<p>La requête retourne un objet JSON contenant une propriété <code>status</code> qui peut valoir "okay" ou "failure". En fonction de ces valeurs, l'objet peut contenir des éléments additionels listés ci-dessous.</p>
<h4 id="okay" name="okay">"okay"</h4>
<p>L'assertion est valide.</p>
<p>Dans ce cas, l'objet JSON contient en plus les propriétés suivantes :</p>
<table class="standard-table" style="width: 80%;">
  <tbody>
    <tr>
      <td>"<code>email</code>"</td>
      <td>L'adresse mail contenue dans l'assertion, pour permettre la connexion de l'utilisateur.</td>
    </tr>
    <tr>
      <td>"<code>audience</code>"</td>
      <td>La valeur audience contenue dans l'assertion. Doit être l'URL de votre propre site.</td>
    </tr>
    <tr>
      <td>"<code>expires</code>"</td>
      <td>La date à laquelle expire l'assertion, exprimée The date the assertion expires, expressed as the <a href="/fr/docs/Référence_de_JavaScript_1.5_Core/Objets_globaux/Date/valueOf" title="en/JavaScript/Reference/Global_Objects/Date/valueOf">primitive value of a Date object</a>&nbsp;qui est le nombre de secondes écoulées depuis le 1er Janvier 1970 00h00 GMT.</td>
    </tr>
    <tr>
      <td>"<code>issuer</code>"</td>
      <td>Le nom du fournisseur d'identité ayant fourni l'assertion.</td>
    </tr>
  </tbody>
</table>
<h4 id="failure" name="failure">"failure"</h4>
<p>L'assertion n'est pas valide.</p>
<p><span style="line-height: 1.572;">Dans ce cas, l'objet JSON contient une propriété additionnelle :</span></p>
<table class="compact-table">
  <tbody>
    <tr>
      <td><code>"reason"</code></td>
      <td>Une chaîne de caractère expliquant pourquoi la validation de l'assertion a échoué</td>
    </tr>
  </tbody>
</table>
<h2 id="Examples" name="Examples">Exemples</h2>
<h3 id="node.js" name="node.js">node.js</h3>
<p>Cet exemple utilise un serveur node.js utilisant express.js</p>
<pre class="brush: js">
var express = require("express"),
    app = express.createServer(),
    https = require("https"),
    querystring = require("querystring");
/* ... */

// La variable audience doit correspondre à ce qu'affiche la barre d'adresse du navigateur,
// ce qui inclut le protocole, le nom de domaine et le port
var audience = "http://localhost:8888";

app.post("/authenticate", function(req, res) {
  var vreq = https.request({
    host: "verifier.login.persona.org",
    path: "/verify",
    method: "POST"
  }, function(vres) {
    var body = "";
    vres.on('data', function(chunk) { body+=chunk; } )
        .on('end', function() {
          try {
            var verifierResp = JSON.parse(body);
            var valid = verifierResp &amp;&amp; verifierResp.status === "okay";
            var email = valid ? verifierResp.email : null;
            req.session.email = email;
            if (valid) {
              console.log("l'assertion a été vérifiée avec succès pour le mail :", email);
              res.json(email);
            } else {
              console.log("l'assertion n'a pas été validée pour la raison suivante :", verifierResp.reason);
              res.send(verifierResp.reason, 403);
            }
          } catch(e) {
            console.log("le verifier n'a pas renvoyé un objet JSON");
            // bogus response from verifier!
            res.send("bogue de la part du verifier !", 403);

          }
        });
  });

  vreq.setHeader('Content-Type', 'application/x-www-form-urlencoded');

  var data = querystring.stringify({
    assertion: req.body.assertion,
    audience: audience
  });

  vreq.setHeader('Content-Length', data.length);
  vreq.write(data);
  vreq.end();

  console.log("vérification de l'assertion");
});

</pre>
<p>via <a class="link-https" href="https://github.com/lloyd/myfavoritebeer.org/blob/06255b960e1f9078bc935c1c7af0662f33c88818/server/main.js#L112">Lloyd Hilaiel</a></p>
<h3 id="PHP" name="PHP">PHP</h3>
<pre class="brush: php">
$url = 'https://verifier.login.persona.org/verify';
$assert = filter_input(
&nbsp;&nbsp;&nbsp; INPUT_POST,
&nbsp;&nbsp;&nbsp; 'assertion',
&nbsp;&nbsp;&nbsp; FILTER_UNSAFE_RAW,
&nbsp;&nbsp;&nbsp; FILTER_FLAG_STRIP_LOW|FILTER_FLAG_STRIP_HIGH
);
//utiliser la superglobale $_POST pour PHP &lt; 5.2 et écrire votre propre filtre 
$params = 'assertion=' . urlencode($assert) . '&amp;audience=' .
           urlencode('http://example.com:80');
$ch = curl_init();
$options = array(
    CURLOPT_URL =&gt; $url,
    CURLOPT_RETURNTRANSFER =&gt; TRUE,
    CURLOPT_POST =&gt; 2,
    CURLOPT_POSTFIELDS =&gt; $params
);
curl_setopt_array($ch, $options);
$result = curl_exec($ch);
curl_close($ch);
echo $result;</pre>
<p>Via <a class="link-https" href="https://github.com/codepo8/BrowserID-login-with-PHP/blob/184fdb74c8a554461c262875859968154d09288e/verify.php">Christian Heilmann</a></p>
<p>Note: si vous envoyez les paramètres assertion et audience en tant qu'objet JSON, ils <strong>ne doivent pas</strong> être encodés. S'ils sont envoyés en tant que paramètres normaux d'une requête HTTP POST, comme dans l'exemple ci-dessus, ils <strong>doivent</strong> être encodés.</p>
Revenir à cette révision