Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Mozilla Persona integration for Express

tag: v0.0.4

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .npmignore
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 CONTRIBUTING.md
Octocat-spinner-32 README.md
Octocat-spinner-32 index.js
Octocat-spinner-32 package.json
README.md

express-persona Build Status

Mozilla Persona integration for Express. express-persona is designed to quickly get Persona authentication working in your Express application, while following Persona security best practices.

Quick start

Install using npm: npm install express-persona

Include the module inside your Express application:

var express = require("express"),
    app = express.createServer();

app.use(express.bodyParser())
  .use(express.cookieParser())
  .use(express.session({
    secret: "mozillapersona"
  }));

require("express-persona")(app, {
  audience: "http://localhost:8888" // Must match your browser's address bar
});

Add the Persona login to a web page, and send the assertion to your Express application:

loginButton.addEventListener("click", function() {
  navigator.id.get(function(assertion) {
    if (!assertion) {
      return;
    }

    var xhr = new XMLHttpRequest();
    xhr.open("POST", "/persona/verify", true);
    xhr.setRequestHeader("Content-Type", "application/json");
    xhr.addEventListener("loadend", function(e) {
      try {
        var data = JSON.parse(this.response);
        if (data.status === "okay") {
          // the email address the user logged in with
          console.log(data.email);
        } else {
          console.log("Login failed because " + data.reason);
        }
      } catch (ex) {
        // oh no, we didn't get valid JSON from the server
      }
    }, false);
    xhr.send(JSON.stringify({
      assertion: assertion
    }));
  });
}, false);

By default, express-persona adds the users email address to req.session.email when their email is validated.

This library will handle 3 of 4 essential practices for Persona security considerations but you should implement CSRF protection as well. I recommend the built-in express csrf middleware.

Documentation

API

  • require('express-persona') returns function(express, options)
    • express is an instance of the express server that you want to add routes to
    • options is an object. It has one required parameter, audience.

Required options

  • audience - The URL of your express app when viewed in a browser. Must include the protocol, hostname, and port.
    • Example: http://example.org:80, https://example.org:443

Optional options

  • verifyPath - The URL that clients use to verify credentials.
    • Default: /persona/verify
    • Examples: /browserid/verify, /api/verify
  • logoutPath - The URL that clients use to logout.
    • Default: /persona/logout
    • Examples: /browserid/logout, /api/logout
  • sessionKey - The session key to store the validated email in.
    • Default: email
    • Example: user, username

Verify route

  • On success:
{
  "status": "okay"
  "email": "jon@example.org"
}
  • On failure
{
  "status": "failure"
  "reason": "request failed"
}

Logout route

  • Always returns:
{
  "status": "okay"
}

Tests

Running Tests

Run tests using npm test from the root of the repository.

Something went wrong with that request. Please try again.