fxa/packages/browserid-verifier

A BrowserID verification server

This repository contains a flexible BrowserID verification server authored in Node.JS which uses the local verification library.

Getting Started

To run the verification server locally:

$ git clone https://github.com/mozilla/browserid-verifier
$ cd browserid-verifier
$ yarn install
$ yarn start

At this point, your verifier will be running and available to use locally over HTTP.

Configuration

There are several configuration variables which can change the behavior of the server. You can inspect available configuration variables in lib/config.js. You can specify a set of json configuration files using the CONFIG_FILES environment variable (separate each path with a comma (,)). Finally, you can inspect the current server configuration with:

$ node ./lib/server.js -c

Health Checks

The server exports an endpoint at /status that can be polled for server health. When the server is healthy, a 200 HTTP response is returned with a body of OK.

Testing

This package uses Mocha to test its code. By default npm test will test all JS files under tests/.

Test specific tests with the following commands:

# Test only tests/health-check.js
npx mocha tests/health-check.js

# Grep for "test servers should start"
npx mocha -g "test servers should start"

Refer to Mocha's CLI documentation for more advanced test configuration.

API

The server exports an HTTP endpoint at /v2 that can be POSTed to verify BrowserID assertions. Arguments may be provided inside a JSON object. The following are required:

1. Requests must be an HTTP POST.
2. Content-Type must equal application/json
3. POST body must be valid JSON.

The following arguments are supported:

required (string) assertion

A BrowserID assertion

required (string) audience

The origin of the site to which the assertion is expected to be bound.

optional (array of strings) trustedIssuers

An array of domain names that are trusted issuers. Assertions signed by any of the domains in this set will be honored regardless of the presence of a subject or principal in a BrowserID assertion.

Error Response

Example:

$ curl -H 'Content-Type: application/json' \
  -d '{ "audience": "http://example.com", "assertion": "bogus" }' \
  https://verifier.mozcloud.org/v2
{
  "status": "failure",
  "reason": "no certificates provided"
}

Upon failure, the verifier returns a non-200 HTTP status code. Additionally, the response body contains a JSON formated response containing a status key with the value of failure. Additionally, more verbose developer readable information will be available in a string value on the reason key.

Success Response

Example:

$ curl -H 'Content-Type: application/json' \
  -d '{ "audience": "http://123done.org" , "assertion": "eyJhbG...ZEe7A" }'
  https://verifier.mozcloud.org/v2
{
  "audience": "http://123done.org",
  "expires": 1389791993675,
  "issuer": "mockmyid.com",
  "email": "lloyd@mockmyid.com",
  "status": "okay"
}

Upon successful assertion verification, a 200 response will be sent with a JSON formatted body. The body will always include audience, issuer, status (of "okay"), and expires.

Extra IdP claims

The verifier will extract any number of additional claims from the Identity Certificate generated by the Identity Provider. These claims will be returned under a idpClaims top level key in the success response. Hence, an identity certificate which looks like this:

{
  "pubkey": { "...": "..." },
  "sub": "60ae5097-8118-4c58-bb80-7db2742d137e",
  "iat": 1389964111,
  "exp": 1421500111,
  "iss": "example.com",
  "fxa-version": 1,
  "fxa-generation": 504,
  "email": "user@example.com"
}

Upon successful verification (which could only occur via .trustedIssuers because authority lookup will fail), will result in a verifier response like this:

{
  "audience": "...",
  "expires": 1421500111,
  "issuer": "example.com",
  "idpClaims": {
    "fxa-version": 1,
    "fxa-generation": 504,
    "email": "user@example.com"
  },
  "status": "okay"
}