.well-known-browserid

Persona is no longer actively developed by Mozilla. Mozilla has committed to operational and security support of the persona.org services until November 30th, 2016.

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

If you run a website that relies on Persona, you need to implement an alternative login solution for your users before this date.

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.

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, Felipe_Largo, Sheppy, Spirit55555, klondike24, demetris
 Last updated by: wbamberg,