.well-known-browserid

  • Revision slug: Persona/.well-known-browserid
  • Revision title: .well-known-browserid
  • Revision id: 311263
  • Created:
  • Creator: demetris
  • Is current revision? No
  • Comment

Revision Content

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: This page is meant to be helpful, but you should consult the BrowserID Protocol Specification as the authoritative technical reference.

Basic Support Document

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 Document

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": "example.com"
}

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

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 on the bare domain itself, not a subdomain. For example: example.com, not www.example.com
  • If delegating to another Identity Provider, the authority value is a bare domain name of the target IdP.

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

Revision Source

<p>Domains advertise their ability to act as Persona Identity Providers (IdPs) by publishing a support document at <code>/.well-known/browserid</code>. This JSON-formatted document must be served over HTTPS with the content type <code>application/json</code>.</p>
<p>This document may either specify how to provision and authenticate users, or may delegate its authority to another Identity Provider.</p>
<p><strong>Note:</strong> This page is meant to be helpful, but you should consult the <a class="link-https" href="https://github.com/mozilla/id-specs/blob/prod/browserid/index.md">BrowserID Protocol Specification</a> as the authoritative technical reference.</p>
<h2 id="Basic_Support_Document">Basic Support Document</h2>
<p>A domain which directly acts an an IdP must provide three values in its support document:</p>
<ul>
  <li><code>public-key</code>: The public part of the domain's cryptographic key.</li>
  <li><code>authentication</code>: The domain's page for asking users to log in.</li>
  <li><code>provisioning</code>: The domain's page for certifying its users' identities.</li>
</ul>
<h4 id="Example_.2F.well-known.2Fbrowserid_file.3A">Example /.well-known/browserid file:</h4>
<pre class="brush:js;">
{
    "public-key": {
        "algorithm": "RS",
        "n": "82818905405105134410187227495885391609221288015566078542117409373192106382993306537273677557482085204736975067567111831005921322991127165013340443563713385983456311886801211241492470711576322130577278575529202840052753612576061450560588102139907846854501252327551303482213505265853706269864950437458242988327",
        "e": "65537"
    },
    "authentication": "/browserid/sign_in.html",
    "provisioning": "/browserid/provision.html"
}</pre>
<h2 id="Delegated_Support_Document">Delegated Support Document</h2>
<p>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 <code>authority</code> entry.</p>
<h4 id="Example_.2F.well-known.2Fbrowserid.3A">Example /.well-known/browserid:</h4>
<pre class="brush:js;">
{
  "authority": "example.com"
}
</pre>
<p>Then <code>example.com</code> would host its own support document, as per the example above.</p>
<p>A domain may delegate to any other domain, so long as the other domain publishes a <code>/.well-known/browserid</code> document.</p>
<h2 id="Checklist">Checklist</h2>
<ul>
  <li>The document is formatted as valid JSON</li>
  <li>The document is served over SSL</li>
  <li>The document is served with a content type of "<code>application/json</code>"</li>
  <li>The document is hosted on on the bare domain itself, not a subdomain. For example: <code>example.com</code>, not <code>www.example.com</code></li>
  <li>If delegating to another Identity Provider, the <code>authority</code> value is a bare domain name of the target IdP.</li>
</ul>
<p>Many of these can be tested automatically with the <a class="link-https" href="https://github.com/mozilla/browserid/blob/dev/scripts/check_primary_support" title="https://github.com/mozilla/browserid/blob/dev/scripts/check_primary_support">check_primary_support script from the Persona</a> codebase<strong>.</strong></p>
Revert to this revision