Implementing a Persona IdP

  • Revision slug: Persona/Implementing_a_Persona_IdP
  • Revision title: Implementing a Persona IdP
  • Revision id: 377191
  • Created:
  • Creator: iskitz
  • Is current revision? No
  • Comment Minor typo in step #3 of the "The Authentication Page" section.

Revision Content

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 user@dev.example.com.

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!

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.

The current Persona infrastructure does not support the Server Name Indication extension, see issue #2583; this means that only one IdP can exist per IP address. This is an important constraint if your server hosts multiple name-based virtual hosts.

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/address_info?email=user@example.com

https://login.persona.org/wsapi/address_info?email=user@mockmyid.com

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:

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.

Serving The IdP Support 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
  • served over SSL
  • served with a content type of "application/json"
  • served from the host part of the email address, not a subdomain (example.com, not www.example.com)

If delegating to another Identity Provider, the authority value must be a bare domain name of the target IdP.

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 {{ domxref("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 {{ domxref("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 {{ domxref("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 in 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 {{ domxref("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 {{ domxref("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 {{ domxref("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 {{ domxref("navigator.id.raiseAuthenticationFailure()") }}. For example:

    var cancelButton = document.getElementById('cancelButton');
    cancelButton.click = function() { navigator.id.raiseAuthenticationFailure('user clicked cancel') };
    

The JavaScript on an example provisioning 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!

Revision Source

<p>After you've read the <strong><a href="/en/BrowserID/Primary" title="https://developer.mozilla.org/en/BrowserID/IdP">Identity Provider overview</a></strong>, 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 <a href="https://github.com/mozilla/id-specs/blob/prod/browserid/index.md" title="https://github.com/mozilla/id-specs/blob/prod/browserid/index.md">BrowserID specification</a>.</p>
<h2 id="General_advice">General advice</h2>
<h3 id="Make_your_IdP_public">Make your IdP public</h3>
<p>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 <a href="http://123done.org" title="http://123done.org">123done.org</a>. During development, you can deploy your IdP on a subdomain like <code>dev.example.com</code> and attempt to log in with Persona as <code>user@dev.example.com</code>.</p>
<h3 id="Use_browser_developer_tools">Use browser developer tools</h3>
<p>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.</p>
<p>And while you're there, don't forget to read the bodies of network responses!</p>
<h3 id="Check_your_SSL">Check your SSL</h3>
<p>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 <a href="https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt" title="https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt">Mozilla certificate bundle</a>. The easiest way to test this is to get a free server certificate from <a href="https://www.startssl.com/" title="https://www.startssl.com/">StartSSL</a>. You need to include any intermediate certificates required to validate your certificate.</p>
<p>The current Persona infrastructure does not support the <a href="http://en.wikipedia.org/wiki/Server_Name_Indication" title="http://en.wikipedia.org/wiki/Server_Name_Indication">Server Name Indication</a> extension, see <a href="https://github.com/mozilla/browserid/issues/2583" title="https://github.com/mozilla/browserid/issues/2583">issue #2583</a>; this means that only one IdP can exist per IP address. This is an important constraint if your server hosts multiple name-based virtual hosts.</p>
<p>Development and testing environments support the use of self-signed certificates.</p>
<h3 id="Use_the_Persona_debugging_tools">Use the Persona debugging tools</h3>
<p>The <span class="external link-https"><a href="https://github.com/mozilla/browserid/blob/dev/scripts/check_primary_support" title="https://github.com/mozilla/browserid/blob/dev/scripts/check_primary_support"><code>check_primary_support</code></a> script</span><span class="external link-https"> tests varies aspects of your IdP configuration, including:</span></p>
<ul>
  <li>that your <code>/.well-known/browserid</code> file:
    <ul>
      <li>is valid JSON</li>
      <li>contains the three mandatory elements: <code class="js string">public-key</code> , <code>authentication</code>, and <code>provisioning</code></li>
      <li>contains a syntactically correct public key as its <code class="js string">public-key </code>element</li>
      <li>contains valid URLs for its <code>authentication</code> and <code>provisioning</code> elements</li>
    </ul>
  </li>
  <li>that the files pointed to in <code>authentication</code> and <code>provisioning</code>:
    <ul>
      <li>can be successfully retrieved</li>
      <li>include the correct JavaScript libraries from Persona</li>
      <li>are not served with the <a href="/en-US/docs/The_X-FRAME-OPTIONS_response_header" title="/en-US/docs/The_X-FRAME-OPTIONS_response_header"><code>X-Frame-Options: DENY</code></a> header</li>
    </ul>
  </li>
</ul>
<p>You can also verify if Persona thinks your domain is an IdP by using the <code>address_info</code> Persona API, passing an email address in your domain. For example, see the difference between these two examples:</p>
<p><a href="https://login.persona.org/wsapi/address_info?email=user%40example.com" title="https://login.persona.org/wsapi/address_info?email=user%40example.com"><code>https://login.persona.org/wsapi/address_info?email=user@example.com</code></a></p>
<p><a href="https://login.persona.org/wsapi/address_info?email=user%40mockmyid.com" title="https://login.persona.org/wsapi/address_info?email=user%40example.com"><code>https://login.persona.org/wsapi/address_info?email=user@mockmyid.com</code></a></p>
<h3 id="Testing_against_pre-release_versions_of_Persona">Testing against pre-release versions of Persona</h3>
<p>If you want to test your IdP against a pre-release version of Persona, then there's an extra consideration.</p>
<p>For login to work, both the Relying Parties (RPs) and the IdP must load the Persona JavaScript libraries from the same domain. In production:</p>
<ul>
  <li>your IdP uses <a href="https://login.persona.org/provisioning_api.js" title="https://login.persona.org/provisioning_api.js">https://login.persona.org/provisioning_api.js</a> and <a href="https://login.persona.org/authentication_api.js" title="https://login.persona.org/provisioning_api.js">https://login.persona.org/authentication_api.js</a></li>
  <li>RPs use&nbsp; <a href="https://login.persona.org/include.js" title="https://login.persona.org/include.js">https://login.persona.org/include.js</a>.</li>
</ul>
<p>But if you want your IdP to use the development version of Persona, which is hosted at <a href="https://login.dev.anosrep.org" title="https://login.dev.anosrep.org">login.dev.anosrep.org</a>, then production RPs like <a href="http://123done.org" title="http://123done.org">123done.org</a> won't be able to use it. You could use your own RP to test with, or an alternative version of <a href="http://123done.org" title="http://123done.org">123done.org</a> , as detailed in the table below:</p>
<table>
  <thead>
    <tr>
      <th scope="row">&nbsp;</th>
      <th scope="col"><strong>Website</strong></th>
      <th scope="col"><strong>Persona Domain</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><strong>Production</strong></th>
      <td><a href="http://123done.org" title="http://123done.org">123done.org</a></td>
      <td><a href="https://login.persona.org" title="https://login.persona.org">login.persona.org</a></td>
    </tr>
    <tr>
      <th scope="row"><strong>Staging</strong></th>
      <td><a href="http://beta.123done.org" title="http://beta.123done.org">beta.123done.org</a></td>
      <td><a href="https://login.anosrep.org" title="https://login.anosrep.org">login.anosrep.org</a></td>
    </tr>
    <tr>
      <th scope="row"><strong>Development</strong></th>
      <td><a href="http://dev.123done.org" title="http://dev.123done.org">dev.123done.org</a></td>
      <td><a href="https://login.dev.anosrep.org" title="https://login.dev.anosrep.org">login.dev.anosrep.org</a></td>
    </tr>
  </tbody>
</table>
<p>If you want to be able to test completely locally, without retrieving the JavaScript libraries from <code>login.persona.org</code>, you can run a local instance of the <a href="https://github.com/mozilla/browserid" title="https://github.com/mozilla/browserid">Persona implementation</a> and point your script tags to that. The implementation also provides a local Persona-enabled site to log into. However, <strong>this option is not recommended</strong> unless you are comfortable with Node.js and grepping around the source. If you go this route, you'll want to look into the <code>SHIMMED_PRIMARIES</code> environment variable to ease pointing your local Persona instance to your local IdP.</p>
<h2 id="Serving_The_IdP_Support_Document">Serving The IdP Support Document</h2>
<p>First, generate a public/private keypair to use with your domain. For example, you can use the command-line openssl tools:</p>
<pre>
openssl genrsa -out private-key.pem 2048
openssl rsa -in private-key.pem -pubout &gt; public-key.pem
</pre>
<p>You can also use the <a class="external" href="https://github.com/mozilla/jwcrypto/blob/master/bin/generate-keypair" title="https://github.com/mozilla/jwcrypto/blob/master/bin/generate-keypair"><code>generate-keypair</code></a> script bundled with <a class="external" href="https://github.com/mozilla/jwcrypto" title="https://github.com/mozilla/jwcrypto">jwcrypto.</a></p>
<p>Next, decide what URLs you want to use for certificate provisioning and user login.</p>
<p>Finally, all of this information must be published in a JSON file at <code>/.well-known/browserid</code>. An example might look like:</p>
<pre class="brush:js;">
{
    "public-key": {
        "algorithm": "RS",
        "n": "82818905405105134410187227495885391609221288015566078542117409373192106382993306537273677557482085204736975067567111831005921322991127165013340443563713385983456311886801211241492470711576322130577278575529202840052753612576061450560588102139907846854501252327551303482213505265853706269864950437458242988327",
        "e": "65537"
    },
    "authentication": "/persona/sign_in.html",
    "provisioning": "/persona/provision.html"
}</pre>
<p>Double check that the document is:</p>
<ul>
  <li>formatted as valid JSON</li>
  <li>served over SSL</li>
  <li>served with a content type of "<code>application/json</code>"</li>
  <li>served from the host part of the email address, not a subdomain (<code>example.com</code>, not <code>www.example.com</code>)</li>
</ul>
<p>If delegating to another Identity Provider, the <code>authority</code> value must be a bare domain name of the target IdP.</p>
<h2 id="The_Provisioning_Page">The Provisioning Page</h2>
<p>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 <a href="/en-US/docs/The_X-FRAME-OPTIONS_response_header" title="/en-US/docs/The_X-FRAME-OPTIONS_response_header"><code>X-Frame-Options: DENY</code></a>.</p>
<p>On the page, you should:</p>
<ol>
  <li>
    <p>Include the Provisioning API library from the correct server (always <code>login.persona.org</code>, unless you're testing with a pre-release version of Persona):</p>
    <pre class="brush:html">
&lt;script src="https://login.persona.org/provisioning_api.js"&gt;&lt;/script&gt;</pre>
  </li>
  <li>
    <p>Invoke {{ domxref("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):</p>
    <pre class="brush:js">
navigator.id.beginProvisioning(function(email, certDuration) {
  //...
});
</pre>
  </li>
  <li>
    <p>Inside the <code>beginProvisioning</code> 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.</p>
    <ol style="list-style-type: lower-alpha">
      <li>
        <p>If the user <strong>does not</strong> have an active session associated with the given email address, call {{ domxref("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 <code>authentication</code> page.</p>
      </li>
      <li>
        <p>If the user <strong>does</strong> have an active session associated with the given email address, continue.</p>
      </li>
    </ol>
  </li>
  <li>
    <p>Inside the <code>beginProvisioning</code> callback, invoke {{ domxref("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):</p>
    <pre class="brush:js">
navigator.id.genKeyPair(function(publicKey) {
  //...
});
</pre>
  </li>
  <li>
    <p>Send the user's <code>publicKey</code> and the desired <code>certDuration</code> to your backend to create a signed certificate, noting that the <code>certDuration</code> must never exceed 24 hours. A common pattern in 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.</p>
    <p>Mozilla provides an open source <a href="https://github.com/mozilla/browserid-certifier" title="https://github.com/mozilla/browserid-certifier">Node.js server</a> to handle certificate work. You can run this behind your firewall and use its REST API to generate signed certificates.</p>
  </li>
  <li>
    <p>Once you have the signed certificate, pass it to {{ domxref("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 <code>certDuration</code>.</p>
  </li>
</ol>
<p>The JavaScript on an example provisioning page might be structured like this:</p>
<pre class="brush:js">
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');
  }
});
</pre>
<h2 id="The_Authentication_Page">The Authentication Page</h2>
<p>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 <a href="/en-US/docs/Web_Development/Responsive_Web_design" title="/en-US/docs/Web_Development/Responsive_Web_design">responsive web design</a> 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.</p>
<p>On this page, you should:</p>
<ol>
  <li>
    <p>Include the Authentication API library from the correct server (always <code>login.persona.org</code>, unless you're testing with a pre-release version of Persona):</p>
    <pre class="brush:html">
&lt;script src="https://login.persona.org/authentication_api.js"&gt;&lt;/script&gt;</pre>
  </li>
  <li>
    <p>Invoke {{ domxref("navigator.id.beginAuthentication()") }}. It takes a callback with one argument (a String), the email address that the user wants to authenticate with:</p>
    <pre class="brush:js">
navigator.id.beginAuthentication(function(email) {
  //...
});
</pre>
  </li>
  <li>
    <p>Inside the <code>beginAuthentication</code> callback, determine if the user actually owns the given email address by checking for an active session with your domain.</p>
    <ol style="list-style-type: lower-alpha">
      <li>
        <p>If the user <strong>does</strong> have an active session associated with the given email address, call {{ domxref("navigator.id.completeAuthentication()") }}. This causes the browser to leave the authentication flow and return to the provisioning process.</p>
      </li>
      <li>
        <p>If the user <strong>does not</strong> have an active session associated with the given email address, continue.</p>
      </li>
    </ol>
  </li>
  <li>
    <p>Ask the user to log in through your normal means of authentication.</p>
  </li>
  <li>
    <p>If there is an error or you wish to cancel the authentication process, invoke {{ domxref("navigator.id.raiseAuthenticationFailure()") }}. For example:</p>
    <pre class="brush:js">
var cancelButton = document.getElementById('cancelButton');
cancelButton.click = function() { navigator.id.raiseAuthenticationFailure('user clicked cancel') };
</pre>
  </li>
</ol>
<p>The JavaScript on an example provisioning page might be structured like this:</p>
<pre class="brush:js;">
navigator.id.beginAuthentication(function(email) {
  if (activeSessionFor(email)) {
    navigator.id.completeAuthentication();
  } else {
    displayLoginForm();
  }
});
</pre>
<h2 id="Wrap_Up">Wrap Up</h2>
<p>With the support document, the provisioning page, and the authentication page in place, you're now a Persona Identity Provider!</p>
Revert to this revision