.well-known-browserid

On November 30th, 2016, Mozilla shut down the persona.org services. Persona.org and related domains will soon be taken offline.

For more information, see this guide to migrating your site away from Persona:

https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers

Domains advertise their ability to act as Persona Identity Providers (IdPs) by publishing a support document at /.well-known/browserid. This JSON-formatted document must be served over HTTPS with the content type application/json.

This document may either specify how to provision and authenticate users, or may delegate its authority to another Identity Provider.

Note: you should also consult the BrowserID Protocol Specification as the authoritative technical reference.

Basic Support

A domain which directly acts an an IdP must provide three values in its support document:

public-key: The public part of the domain's cryptographic key.
authentication: The domain's page for asking users to log in.
provisioning: The domain's page for certifying its users' identities.

Example /.well-known/browserid file:

{
    "public-key": {
        "algorithm": "RS",
        "n": "82818905405105134410187227495885391609221288015566078542117409373192106382993306537273677557482085204736975067567111831005921322991127165013340443563713385983456311886801211241492470711576322130577278575529202840052753612576061450560588102139907846854501252327551303482213505265853706269864950437458242988327",
        "e": "65537"
    },
    "authentication": "/browserid/sign_in.html",
    "provisioning": "/browserid/provision.html"
}

Delegated Support

HTTP redirects and other means of "moving" a /.well-known/browserid file are not permitted. If an IdP would like to delegate to another domain for authentication and provisioning, it may publish a support document which only contains an authority entry.

Example /.well-known/browserid:

{
  "authority": "subdomain.example.com"
}

Then subdomain.example.com would host its own support document, as per the example above.

The authority field is specified as a hostname plus, optionally, a port. It may not contain a path. So "example.com", "subdomain.example.com", and "subdomain.example.com:8080" are all valid, but "subdomain.example.com/login" is not.

A domain may delegate to any other domain, so long as the other domain publishes a /.well-known/browserid document.

Checklist

The document is formatted as valid JSON
The document is served over SSL
The document is served with a content type of "application/json"
The document is hosted on the domain exactly matching that in the email addresses assigned to users. For example: example.com, not www.example.com.
If delegating to another Identity Provider, the authority value is specified only as a hostname and, optionally, a port.

Many of these can be tested automatically with the check_primary_support script from the Persona codebase.