Implementing a Persona IdP

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, and provisioning
  • contains a syntactically correct public key as its public-key element
  • contains valid URLs for its authentication and provisioning elements
• that the files pointed to in authentication and provisioning:
  • 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:

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, not www.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:

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

2. 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) {
     //...
   });
   

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

   1. 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 your authentication page.

   2. If the user does have an active session associated with the given email address, continue.

4. Inside the beginProvisioning callback, invoke navigator.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) {
     //...
   });
   

5. Send the user's publicKey and the desired certDuration to your backend to create a signed certificate, noting that the certDuration 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.

6. 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 the certDuration.

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:

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

2. 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) {
     //...
   });
   

3. Inside the beginAuthentication callback, determine if the user actually owns the given email address by checking for an active session with your domain.

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

   2. If the user does not have an active session associated with the given email address, continue.

4. Ask the user to log in through your normal means of authentication.

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