Nice Paintings, Mondrian
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    express-personapublic

    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();
     
    app.use(express.json())
      .use(express.urlencoded())
      .use(express.cookieParser())
      .use(express.session({
       secret: "mozillapersona"
      }));
     
    require("express-persona")(app, {
      audience: "http://localhost:8888" // Must match your browser's address bar
    });

    Include the Persona library in your web page:

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

    Add login and logout functionality to your buttons:

    document.querySelector("#login").addEventListener("click", function() {
      navigator.id.request();
    }, false);
     
    document.querySelector("#logout").addEventListener("click", function() {
      navigator.id.logout();
    }, false);

    Watch for login and logout actions:

    navigator.id.watch({
      onlogin: function(assertion) {
        var xhr = new XMLHttpRequest();
        xhr.open("POST", "/persona/verify", true);
        xhr.setRequestHeader("Content-Type", "application/json");
        xhr.addEventListener("loadend", function(e) {
          var data = JSON.parse(this.responseText);
          if (data && data.status === "okay") {
            console.log("You have been logged in as: " + data.email);
          }
        }, false);
     
        xhr.send(JSON.stringify({
          assertion: assertion
        }));
      },
      onlogout: function() {
        var xhr = new XMLHttpRequest();
        xhr.open("POST", "/persona/logout", true);
        xhr.addEventListener("loadend", function(e) {
          console.log("You have been logged out");
        });
        xhr.send();
      }
    });

    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.

    You can view and run complete examples in the examples directory.

    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
    • verifierURI - The URI of the Persona Remote Verification API
      • Default: https://verifier.login.persona.org/verify
      • You probably don't want to touch this unless you have a good reason, like testing.
    • verifyResponse(error, req, res, email) - Function to generate response for verify route
      • Default: see Verify route, below, for successess and failure responses
      • error will be a string suitable for display (the "reason" attribute in the default implementation), if an error occurs
      • req, res are the request and response objects
      • email is a string containing the email, and will exist if there is not an error
    • logoutResponse(error, req, res) - Function to generate response for logout route
      • Default: see Logout route, below, for response
      • error will be a string suitable for display, if an error occurs
      • req, res are the request and response objects
    • middleware(req, res, next) - Custom middleware for logout/login routes
      • Default: none
      • req, res are the request and response objects
      • next points to the next middleware function in the chain

    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.

    install

    npm i express-persona

    Downloadsweekly downloads

    42

    version

    0.1.2

    license

    BSD

    repository

    githubgithub

    last publish

    collaborators

    • avatar