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
After you've read the Identity Provider overview, this document will guide you through implementing a Persona Identity Provider (IdP). This page provides a guide to implementating an IdP. For details of the current data formats used by Persona, you should refer to the BrowserID specification.
General advice
Make your IdP public
For ease of development, it helps to have your IdP available on the public internet so that you can test it using Persona-enabled sites like 123done.org. During development, you can deploy your IdP on a subdomain like dev.example.com
and attempt to log in with Persona as [email protected]
.
Use browser developer tools
Due to the way that Persona uses cookies, iframes, localStorage, and postMessage, it can be difficult to get a complete understanding of the interactions between your IdP and Persona by using a single browser's developer tools. Firefox, Chrome, and Opera all have built-in tools that excel at different aspects of debugging IdPs.
And while you're there, don't forget to read the bodies of network responses!
3rd Party Cookies
You should target your production deployment to a domain that your users are already using. Otherwise, 3rd party cookie settings may block your users. During development, you can visit your IdP urls directly to get a cookie, or update your browser to accept all cookies.
Check your SSL
The support document, provisioning page and authentication page must all be available over HTTPS, and the server's SSL certificate must be certified by a trusted CA whose certificate is in the standard Mozilla certificate bundle. The easiest way to test this is to get a free server certificate from StartSSL. You need to include any intermediate certificates required to validate your certificate.
Development and testing environments support the use of self-signed certificates.
Use the Persona debugging tools
The check_primary_support
script tests varies aspects of your IdP configuration, including:
- that your
/.well-known/browserid
file:- is valid JSON
- contains the three mandatory elements:
public-key
,authentication
, andprovisioning
- contains a syntactically correct public key as its
public-key
element - contains valid URLs for its
authentication
andprovisioning
elements
- that the files pointed to in
authentication
andprovisioning
:- can be successfully retrieved
- include the correct JavaScript libraries from Persona
- are not served with the
X-Frame-Options: DENY
header
You can also verify if Persona thinks your domain is an IdP by using the address_info
Persona API, passing an email address in your domain. For example, see the difference between these two examples:
https://login.persona.org/wsapi/[email protected]
https://login.persona.org/wsapi/[email protected]
Testing against pre-release versions of Persona
If you want to test your IdP against a pre-release version of Persona, then there's an extra consideration.
For login to work, both the Relying Parties (RPs) and the IdP must load the Persona JavaScript libraries from the same domain. In production:
- your IdP uses https://login.persona.org/provisioning_api.js and https://login.persona.org/authentication_api.js
- RPs use https://login.persona.org/include.js.
But if you want your IdP to use the development version of Persona, which is hosted at login.dev.anosrep.org, then production RPs like 123done.org won't be able to use it. You could use your own RP to test with, or an alternative version of 123done.org , as detailed in the table below:
Website | Persona Domain | |
---|---|---|
Production | 123done.org | login.persona.org |
Staging | beta.123done.org | login.anosrep.org |
Development | dev.123done.org | login.dev.anosrep.org |
If you want to be able to test completely locally, without retrieving the JavaScript libraries from login.persona.org
, you can run a local instance of the Persona implementation and point your script tags to that. The implementation also provides a local Persona-enabled site to log into. However, this option is not recommended unless you are comfortable with Node.js and grepping around the source. If you go this route, you'll want to look into the SHIMMED_PRIMARIES
environment variable to ease pointing your local Persona instance to your local IdP.
The IdP support document
IdPs advertise their support for the BrowserID protocol with a document called browserid
. For more details of the document's format, see /.well-known/browserid
.
Creating the browserid document
First, generate a public/private keypair to use with your domain. For example, you can use the command-line openssl tools:
openssl genrsa -out private-key.pem 2048 openssl rsa -in private-key.pem -pubout > public-key.pem
You can also use the generate-keypair
script bundled with jwcrypto.
Next, decide what URLs you want to use for certificate provisioning and user login.
Finally, all of this information must be published in a JSON file at /.well-known/browserid
. An example might look like:
{ "public-key": { "algorithm": "RS", "n": "82818905405105134410187227495885391609221288015566078542117409373192106382993306537273677557482085204736975067567111831005921322991127165013340443563713385983456311886801211241492470711576322130577278575529202840052753612576061450560588102139907846854501252327551303482213505265853706269864950437458242988327", "e": "65537" }, "authentication": "/persona/sign_in.html", "provisioning": "/persona/provision.html" }
Double check that the document is formatted as valid JSON.
You can use this file to delegate to another Identity Provider: see Delegated Support for details.
Serving the browserid document
This document must be served:
- over SSL
- with a content type of "
application/json
" - from the exact host part of the email address, not a subdomain (
example.com
, notwww.example.com
)
The provisioning page
The provisioning page must respond to GET requests. Persona uses a hidden iframe to access your provisioning page, so its contents will never be visible to the user. The iframe technique also means that the headers sent with your provisioning page must not include X-Frame-Options: DENY
.
On the page, you should:
-
Include the Provisioning API library from the correct server (always
login.persona.org
, unless you're testing with a pre-release version of Persona):<script src="https://login.persona.org/provisioning_api.js"></script>
-
Invoke
navigator.id.beginProvisioning()
. It takes a callback with two arguments, the user's email address (a String) and a desired certificate duration (a Number, in seconds):navigator.id.beginProvisioning(function(email, certDuration) { //... });
-
Inside the
beginProvisioning
callback, determine if the user actually owns the given email address by checking for an active session with your domain. Note that cookies set for your domain won't be sent to the provisioning page if the user has set their user agent to disable third-party cookies.-
If the user does not have an active session associated with the given email address, call
navigator.id.raiseProvisioningFailure()
with an optional, but recommended, error message at its first parameter. This causes the browser to stop the provisioning process and instead show the user yourauthentication
page. -
If the user does have an active session associated with the given email address, continue.
-
-
Inside the
beginProvisioning
callback, invokenavigator.id.genKeyPair()
. It takes a callback with one argument, the user's public key (a String containing a JSON object representing the public key):navigator.id.genKeyPair(function(publicKey) { //... });
-
Send the user's
publicKey
and the desiredcertDuration
to your backend to create a signed certificate, noting that thecertDuration
must never exceed 24 hours. A common pattern is to use an AJAX POST, returning the certificate in the response. The certificate must be signed by the private key corresponding to the public key advertised in your domain's support document.Mozilla provides an open source Node.js server to handle certificate work. You can run this behind your firewall and use its REST API to generate signed certificates.
-
Once you have the signed certificate, pass it to
navigator.id.registerCertificate()
to save it in the user's browser. This certificate will allow the user to log into sites using Persona for as long as thecertDuration
.
The JavaScript on an example provisioning page might be structured like this:
navigator.id.beginProvisioning(function(email, certDuration) { if (activeSessionFor(email)) { navigator.id.genKeyPair(function(publicKey) { generateServerSide(email, publicKey, certDuration, function (certificate) { // generateServerSide something you would write. // In this example, imagine it does an AJAX request to create a certificate, // and then invokes a callback with that certificate. navigator.id.registerCertificate(certificate); }); }); } else { navigator.id.raiseProvisioningFailure('user is not authenticated as target user'); } });
The authentication page
The authentication page must respond to GET requests. It will be shown to the user in a top-level window (so you can use images and CSS to create a familar experience), which may be freely resized; this means your authentication page should use responsive web design techniques, as it will appear in everything from small pop-ups to full-screen windows on tablets or in some desktop browsers. Being responsive will ensure that your authentication page looks good in any content frame.
On this page, you should:
-
Include the Authentication API library from the correct server (always
login.persona.org
, unless you're testing with a pre-release version of Persona):<script src="https://login.persona.org/authentication_api.js"></script>
-
Invoke
navigator.id.beginAuthentication()
. It takes a callback with one argument (a String), the email address that the user wants to authenticate with:navigator.id.beginAuthentication(function(email) { //... });
-
Inside the
beginAuthentication
callback, determine if the user actually owns the given email address by checking for an active session with your domain.-
If the user does have an active session associated with the given email address, call
navigator.id.completeAuthentication()
. This causes the browser to leave the authentication flow and return to the provisioning process. -
If the user does not have an active session associated with the given email address, continue.
-
-
Ask the user to log in through your normal means of authentication.
-
If there is an error or you wish to cancel the authentication process, invoke
navigator.id.raiseAuthenticationFailure()
. For example:var cancelButton = document.getElementById('cancelButton'); cancelButton.click = function() { navigator.id.raiseAuthenticationFailure('user clicked cancel') };
The JavaScript on an example authentication page might be structured like this:
navigator.id.beginAuthentication(function(email) { if (activeSessionFor(email)) { navigator.id.completeAuthentication(); } else { displayLoginForm(); } });
Wrap up
With the support document, the provisioning page, and the authentication page in place, you're now a Persona Identity Provider!