Revision 322677 of Implementing a Persona IdP

  • Revision slug: Persona/Implementing_a_Persona_IdP
  • Revision title: Implementing a Persona IdP
  • Revision id: 322677
  • Created:
  • Creator: DirkjanOchtman
  • Is current revision? No
  • Comment Remove confusing notion of "bare domain".
Tags: 

Revision Content

After you've read the IdP overview, this document will guide you through implementing a Persona IdP. This page provides a guide to implementation of an IdP; for details of the current data formats used by Persona, you should refer to the BrowserID specification.

General advice

For ease of development, it helps to have your IdP available on the public internet so that you can test it by 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.

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!

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

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"
}

The support document, provisioning page and authentication page must all be available over HTTPS, using an SSL certificate from a well-known CA. The easiest way to test this is to get a free server certificate from StartSSL. After setting up the SSL certificate, you'll want to double check that:

  • 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 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 is a bare domain name of the target IdP

In particular, Persona's SSL support can be less forgiving than your web browser:

  • The SSL certificate must be signed by a trusted CA (see the bundle of certificates as used by Persona in June 2012)
  • You may need to "bundle" your certificate 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.

Many of these can be tested automatically with the check_primary_support script from the Persona codebase. You can also verify if Persona thinks your domain is an IdP by using https://login.persona.org/wsapi/address_info?email=user@example.com. For more information, check out the IdP Development Tips and the /.well-known/browserid documentation.

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 cannot include X-Frame-Options: DENY.

On the page, you should:

  1. Include the Provisioning API library from the correct server (see appendix):

    <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 the string "user is not authenticated as target user" as its first parameter. (Using any other string as the argument to raiseProvisioningFailure will trigger a general error in Persona sign in, see issue #2239.) 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 (see appendix):

    <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 to 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!

Appendix: testing against staging or development versions

For login to work, both the website you're logging into and your IdP must load include.js, provisioning_api.js, and authentication_api.js from the same domain. This means that if the site you're logging in to uses https://login.persona.org/include.js, then your IdP must use https://login.persona.org/provisioning_api.js and so on. In production, this should always be https://login.persona.org/.

These domains only a concern if you want to test your IdP against pre-release versions of Persona. In that case, you'll have to log into a website that also uses the same pre-release version of Persona. You can also use the sites 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.

Revision Source

<p>After you've read the <strong><a href="/en/BrowserID/Primary" title="https://developer.mozilla.org/en/BrowserID/IdP">IdP overview</a></strong>, this document will guide you through implementing a Persona IdP. This page provides a guide to implementation of 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>
<p>For ease of development, it helps to have your IdP available on the public internet so that you can test it by 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>
<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>
<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</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>The support document, provisioning page and authentication page must all be available over HTTPS, using an SSL certificate from a well-known CA. 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>. After setting up the SSL certificate, you'll want to double check that:</p>
<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 served from the host part of the email address, not a subdomain (<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>In particular, Persona's SSL support can be less forgiving than your web browser:</p>
<ul>
  <li>The SSL certificate must be signed by a trusted CA (see <a href="https://developer.mozilla.org/@api/deki/files/6289/=cacert.pem" title="https://developer.mozilla.org/@api/deki/files/6289/=cacert.pem">the bundle of certificates</a> as used by Persona in June 2012)</li>
  <li>You may need to <a href="http://wiki.flexion.org/linux/startssl-certificate/#create_nginx_certificate" title="http://wiki.flexion.org/linux/startssl-certificate/#create_nginx_certificate">"bundle" your certificate</a> to include any intermediate certificates required to validate your certificate</li>
  <li>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)</li>
</ul>
<p>Development and testing environments support the use of self-signed certificates.</p>
<p>Many of these can be tested automatically with the <a class="external 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"><code>check_primary_support</code> script</a><span class="external link-https"> from the Persona</span> codebase<strong>.</strong> You can also verify if Persona thinks your domain is an IdP by using <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>. For more information, check out the <a href="/en-US/docs/BrowserID/Primary/Developer_tips" title="/en-US/docs/BrowserID/Primary/Developer_tips">IdP Development Tips</a> and the <a href="/en-US/docs/Persona/.well-known-browserid" title="/en-US/docs/BrowserID/.well-known-browserid"><code>/.well-known/browserid </code>documentation</a>.</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 cannot 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 (see appendix):</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 the string "<code>user is not authenticated as target user</code>" as its first parameter. (Using any other string as the argument to <code>raiseProvisioningFailure</code> will trigger a general error in Persona sign in, see <a href="https://github.com/mozilla/browserid/issues/2339" title="https://github.com/mozilla/browserid/issues/2339">issue #2239</a>.) 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 (see appendix):</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 to 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>
<h2 id="Appendix.3A_testing_against_staging_or_development_versions">Appendix: testing against staging or development versions</h2>
<p>For login to work, both the website you're logging into and your IdP must load <code>include.js</code>, <code>provisioning_api.js</code>, and <code>authentication_api.js</code> from the same domain. This means that if the site you're logging in to uses <a href="https://login.persona.org/include.js" title="https://login.persona.org/include.js">https://login.persona.org/include.js</a>, then your IdP must use <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 so on. In production, this should <em>always</em> be <a href="https://login.persona.org/" title="https://login.persona.org/">https://login.persona.org/</a>.</p>
<p>These domains only a concern if you want to test your IdP against pre-release versions of Persona. In that case, you'll have to log into a website that also uses the same pre-release version of Persona. You can also use the sites 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>
Revert to this revision