The BrowserID protocol is designed to allow identity providers to directly vouch for their users' ownership of email addresses that they issue. They do this by implementing the BrowserID Primary IdP Protocol. Concretely, this involves the publication resources which advertise support, perform headless certificate provisioning, and expose a web based user interface to allow for authentication to their service from within UI rendered by the browser.
The protocol is designed to be compatible with both an HTML implementation of BrowserID and a native browser implementation.
A BrowserID primary identity authority must implement the following:
- A declaration of support: An IdP must explicitly declare, in the form of a document hosted on their domain, that they support BrowserID. The contents of this document may include paths to supporting resources, as well as a public key which allows for the verification of assertions generated using certificates that the primary has issued.
- Authentication page: A user must be able to interact with their IdP at the time that they are signing into a website to prove their identity to the IdP and establish a session.
- Provisioning page: A webpage must be provided which is capable of provisioning a user that is authenticated to the IdP with a certificate.
The remainder of this document discusses these requirements.
In order to make it possible for the browser to determine if there is
primary support available for a given domain, there must be a well
known location where an expression of support is published. RFC
5785 proposes a convention for well-known resources, such as that
required by BrowserID, which is a .well-known directory under the
document root. Applying this convention, primaries must serve a JSON
document under .well-known/browserid.
This document should:
- be served from
/.well-known/browserid - be served with a
Content-Typeofapplication/json - be provided over SSL.
- have cache headers inline with the desires of the primary
The top level keys present have the following contents and meaning:
- public-key is a public key that can be used to verify that certificates issued by the primary are authentic.
- authentication is a path that serves web content that can be rendered by the browser to allow the user to authenticate to the IdP.
- provisioning is a path to content that is capable of attaining a certificate given an established session with the IdP.
{
"public-key": { <public key as json object> },
"authentication": "/browserid/auth",
"provisioning": "/browserid/provision"
}
In the event that a domain wishes to have primary support for email
addresses underneath it, but wishes for that support to be implemented
by a domain other than its own, it may explicity delegate
authentication and provisioning to another host. Delegation occurs
when an authority property is present in the declaration of support
which contains a domain name (in which case, all other properties
present are ignored).
An example declaration of supporty which delegates is thus:
{
"authority": "otherhost.tld"
}
In attempting to determine whether primary BrowserID support exists
for an email address user@somehost.tld, a browser will first pull
https://somehost.tld/.well-known/browserid; upon discovery of delegated
authority, the browser would next check
https://otherhost.tld/.well-known/browserid.
Normal caching rules apply, and as with HTTP, clients should detect infinite redirection loops and may limit redirection to a reasonable maximum, like 5.
A declaration of support can contain public keys, which may change. At the same time, anyone who verifies assertions must fetch these resources in order to authenticate users. Validity duration is expressed using standard HTTP caching headers, and primaries should allow this resource to be cached at least six hours, with appropriate deployment strategies to gracefully introduce changes. A reasonable cache header on a declaration of support might be:
Cache-Control: public, max-age=21600
In this specification, there's no way for a primary to publish more that
one public key, which would be required to enable transitioning from
one root keypair to another. It's suggested we consider allowing the
public-key property of the declaration of support to have an array of
keys as a value, and update the verification algorithm and formats to
support simple but efficient determination of which public key to use
in the event there are multiple.
The provisioning page is a resource served by the IdP that can interact with the primary provider and the BrowserID JavaScript API to check if the user is authenticated, generated a keypair, sign the public key to create a certificate, and return that certificate to BrowserID via the API.
The provisioning page will run in a headless javascript environment
(the DOM of the content is not displayed), and it may be run in a
sandbox allocated by the browser without access to window.*
properties available to normal web content.
// get parameters of provisioning
navigator.id.beginProvisioning(function(email, cert_duration) {
// ... check if the current user is authenticated as 'email' ...
if (notAuthenticated()) {
navigator.id.raiseProvisioningFailure("user isn't authenticated");
}
// request a keypair be generated by browserid and get the public key
navigator.id.genKeyPair(function(pubkey) {
// ... interact with the server to sign the public key and get
// a certificate ...
var cert = someServerInteraction();
// pass the certificate back to BrowserID and complete the
// provisioning process
navigator.id.registerCertificate(cert);
});
});
To support browsers without native BrowserID support, the provisioning content should include a javascript shim, hosted at:
https://login.persona.org/provisioning_api.js
// A function invoked to fetch provisioning parameters, such as
// email and desired certificate duration.
navigator.id.beginProvisioning(function(email, cert_duration_s) { });
// cause the browser to generate a key-pair, cache the private key
// and return the public key for signing.
navigator.id.genKeyPair(function(pubkey) { });
// upon successful certificate generation, register the certificate
// with the browser.
navigator.id.registerCertificate(certificate);
// in the event of a failure, the provisioning code should
// invoke this function to terminate the provisioning process,
// providing a developer readable reason for the failure.
navigator.id.raiseProvisioningFailure(string reason);
The primary should consider the certificate duration provided by BrowserID to be an upper bound on duration. Under scenarios where the user is on a shared device that is not their own, certificate duration will be shorter. Further, depending on the capabilities of the device, the public key generated maybe be weaker, warranting a reduced duration of validity
Given that these factors, not known to the provisioning page, weigh into certificate duration, the primary should defer to this value, and BrowserID may delete certificates before their expiration if it exceeds the maximum.
When native browser support is not available, provisioning content will be run in an iframe. Certain browser configurations may suppress cookies when content is run in such an environment. Primary providers that want to improve their browser support should consider alternate authentication mechansims to support browsers with this featuere.
When a fatal error that will prevent provisioning from completing successfully
is detected, the provisioning content should invoke
navigator.id.raiseProvisioningFailure(). This ends the provisioning attempt
and indicates that the evaluation context in which the provisioning code is
running can be immediately destroyed.
The primary may provide a developer readable error string that may be outputted on a browser-specific error console to facilitate debugging.
A BrowserID implementation should detect when the provisioning content has become non-responsive. Provisioning code, in turn, should follow the following guidelines to facilitate this detection and prevent false positives:
- Upon content load invoke
navigator.id.beginProvisioning()promptly to indicate successful load and initiation. - Only after it has been verified that the user is authenticated as
the target email should
.genKeyPair()be invoked.
The authentication page is displayed from within UI rendered by the browser after silent provisioning fails, and is intended to allow the user to provide authentication credentials to the primary as part of authenticating to a website.
The authentication page should be designed to work well on mobile devices and desktops. For the latter, the IdP may assume a resolution of 700 pixels by 375 pixels.
Subsequent to this interaction, the BrowserID dialog will re-attempt the provisioning process, and the results of that will indicate whether the user has successfully authenticated with the primary.
// set up UI
navigator.id.beginAuthentication(function(email) {
// update UI to display the email address
});
function onAuthentication() {
// check if the user authenticated successfully, if not, tell them
// it's a bad password. otherwise..
navigator.id.completeAuthentication();
}
function onCancel() {
navigator.id.cancelAuthentication();
}
To support browsers without native BrowserID support, the authentication page should include a javascript shim, hosted at:
https://login.persona.org/authentication_api.js
// Access the email that the user has specified they would like
// to use to sign in.
navigator.id.beginAuthentication(function(email) { });
// Indicate that the authentication process has completed
// successfully
navigator.id.completeAuthentication();
// Indicate that the authentication process has failed, optionally
// providing a developer readable reason.
navigator.id.raiseAuthenticationFailure(string reason);
The public key is a JSON Web Algorihtms (JWA) public key as listed here. The EyeDeeMe service has a .well-known/browserid document that shows exactly what the Mozilla Wiki means in the example. The EyeDeeMee key is an RSA public key than can be generated using OpenSSL.
Generate a public key JSON document in Ruby:
private_key = OpenSSL::PKey::RSA.new(1024)
public_key = private_key.public_key
{ "algorithm" => "RS", "n" => public_key.n.to_s, "e" => public_key.e.to_s }.to_json
XXX: write me or point to another document
XXX: write me or point to another document