Implementing a Persona IdP

  • Revision slug: Persona/Implementing_a_Persona_IdP
  • Revision title: Implementing a Persona IdP
  • Revision id: 298024
  • Created:
  • Creator: Callahad
  • Is current revision? No
  • Comment

Revision Content

After you've read the IdP overview, this document will guide you through implementing a Persona IdP.

The IdP Support Document

First, generate a public/private keypair to use with your domain. You can use the generate-keypair script bundled with jwcrypto, since the BrowserID protocol is based the Javascript Object Signing and Encryption standards being developed by the IETF. You should refer to the BrowserID specification for details of the current format used by Persona.

Second, decide what URLs you want to use for user login and certificate provisioning.

Finally, create a new JSON file at /.well-known/browserid and add all of the above information to it. 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, authentication page, and provisioning page must all be available over HTTPS, using an SSL certificate from a well-known CA. Persona's list of trusted CAs is derived from the list shipped with Firefox. 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. Its contents will never be visibile to the user. In the page, you should:

  1. Include the Provisioning API library:

    <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 and a desired certificate duration:

    navigator.id.beginProvisioning(function(email, cert_duration) {
      //...
    });
    
  3. Inside the beginProvisioning 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 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. 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:

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

The JavaScript on an example provisioning page might be structured like this:

navigator.id.beginProvisioning(function(email, cert_duration) {
  if (activeSessionFor(email)) {
    navigator.id.genKeyPair(function(publicKey) {
      generateServerSide(publicKey, cert_duration, 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 provisioning page must respond to GET requests. It will be shown to the user, and may be freely resized. In the page, you should:

  1. Include the Provisioning API library:

    <script src="https://login.persona.org/authentication_api.js"></script>
  2. Determine the user's login state and which email addresses they control.

  3. Invoke {{ domxref("navigator.id.beginAuthentication()") }}. It takes a callback with one argument, the email address that the user wants to authenticate with:

    navigator.id.beginAuthentication(function(email) {
      //...
    });
    
  4. 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 associted 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 associted with the given email address, continue.

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

  6. 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();
  }
});

The authentication flows run in a user-visible top level window, so you can use images and CSS to create a familar experience.

Wrap Up

With the support document, the provisioning page, and the authentication page in place, you're now a Persona Identity Provider!

Be sure to check out the IdP Development Tips for information on testing your IdP and getting it online.

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.</p>
<h2 id="The_IdP_Support_Document">The IdP Support Document</h2>
<p>First, generate a public/private keypair to use with your domain. You can 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>, since the BrowserID protocol is based the <a href="http://datatracker.ietf.org/wg/jose/charter/" title="http://datatracker.ietf.org/wg/jose/charter/">Javascript Object Signing and Encryption</a> standards being developed by the IETF. 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> for details of the current format used by Persona.</p>
<p>Second, decide what URLs you want to use for user login and certificate provisioning.</p>
<p>Finally, create a new JSON file at <code>/.well-known/browserid</code> and add all of the above information to it. 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, authentication page, and provisioning page must all be available over HTTPS, using an SSL certificate from a well-known CA. Persona's list of trusted CAs is derived from the list shipped with Firefox. 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. Its contents will never be visibile to the user. In the page, you should:</p>
<ol>
  <li>
    <p>Include the Provisioning API library:</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 and a desired certificate duration:</p>
    <pre class="brush:js">
navigator.id.beginProvisioning(function(email, cert_duration) {
  //...
});
</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.</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. 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:</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>cert_duration</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, cert_duration) {
  if (activeSessionFor(email)) {
    navigator.id.genKeyPair(function(publicKey) {
      generateServerSide(publicKey, cert_duration, 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 provisioning page must respond to GET requests. It will be shown to the user, and may be freely resized. In the page, you should:</p>
<ol>
  <li>
    <p>Include the Provisioning API library:</p>
    <pre class="brush:html">
&lt;script src="https://login.persona.org/authentication_api.js"&gt;&lt;/script&gt;</pre>
  </li>
  <li>
    <p>Determine the user's login state and which email addresses they control.</p>
  </li>
  <li>
    <p>Invoke {{ domxref("navigator.id.beginAuthentication()") }}. It takes a callback with one argument, 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 associted 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 associted 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>
<p>The authentication flows run in a user-visible top level window, so you can use images and CSS to create a familar experience.</p>
<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>
<p>Be sure to check out the <a href="/en-US/docs/BrowserID/Primary/Developer_tips" title="/en-US/docs/BrowserID/Primary/Developer_tips">IdP Development Tips</a> for information on testing your IdP and getting it online.</p>
Revert to this revision