mozilla
Your Search Results

    .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.

    Document Tags and Contributors

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