.well-known-browserid

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.