Summary

When a user tries to log into a website, their browser generates a data structure called an assertion, which is essentially a cryptographically signed email address. The browser sends this assertion to the website, which must verify that the assertion is valid before logging the user in.

Assertions can be verified locally, or with an API hosted at https://verifier.login.persona.org/verify. This page describes how to use the API.

Method

HTTP POST request to https://verifier.login.persona.org/verify.

Parameters

assertion

The assertion supplied by the user. Available as the first parameter passed to the onlogin function in navigator.id.watch().

audience

The protocol, domain name, and port of your site. For example, "https://example.com:443".

Return values

The call returns a JSON structure containing a status element, which may be either "okay" or "failure". Depending on the value of status, the structure contains additional elements listed below.

"okay"

The assertion is valid.

In this case the JSON structure contains the following additional elements:

"failure"

The assertion is invalid. In this case, the JSON structure contains one additional element:

Examples

node.js

This example uses a node.js server using express.js

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

// The audience must match what your browser's address bar shows,
// including protocol, hostname, and 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("assertion verified successfully for email:", email);
              res.json(email);
            } else {
              console.log("failed to verify assertion:", verifierResp.reason);
              res.send(verifierResp.reason, 403);
            }
          } catch(e) {
            console.log("non-JSON response from verifier");
            // bogus response from verifier!
            res.send("bogus response from 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("verifying 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
);
//Use the $_POST superglobal array for PHP < 5.2 and write your own filter
$params = 'assertion=' . urlencode($assert) . '&audience=' .
           urlencode('http://localhost:8888');
$ch = curl_init();
$options = array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_POST => 2,
    //CURLOPT_SSL_VERIFYPEER => true,   //This currently blocks connection to 'https://verifier.login.persona.org/verify'
    CURLOPT_SSL_VERIFYPEER => 0,

    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_POSTFIELDS => $params
);
curl_setopt_array($ch, $options);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Via Christian Heilmann

Java

@Override
protected void doPost(final HttpServletRequest req,
   final HttpServletResponse resp) throws ServletException,
   IOException {

   final String audience = req.getServerName();
   final String assertion = req.getParameter("assertion");
   final Verifier verifier = new Verifier();
   final BrowserIDResponse personaResponse = verifier.verify(assertion,audience);
   final Status status = personaResponse.getStatus();

   if (status == Status.OK) {
     /* Authentication with Persona was successful */
     String email = personaResponse.getEmail();
     log.info("{} has sucessfully signed in", email);
     HttpSession session = req.getSession(true);
     session.setAttribute("email", email);

   } else {
     /* Authentication with Persona failed */
     log.info("Sign in failed...");

   }
}

Via Javier

Note: If you send the assertion and audience parameters as a JSON-object, they must not be URL-encoded. If they are sent as regular HTTP POST parameters, as in the example above, they must be URL-encoded.