mozilla

Revision 297169 of IdP Development Tips

  • Revision slug: BrowserID/Primary/Developer_tips
  • Revision title: IdP Development Tips
  • Revision id: 297169
  • Created:
  • Creator: Callahad
  • Is current revision? No
  • Comment

Revision Content

Development Tips for Identity Providers

Use Responsive Design Techniques

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.

Generating Keys

To generate a keypair suitable for use with Persona, you can use the generate-keypair script bundled with jwcrypto.

Serving the Support Document

To be recognized as an Identity Provider, your domain must publish a support document at /.well-known/browserid. Be sure to review its documentation.

In particular, 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 hosted on on the bare domain itself, not a subdomain. For example: example.com, not www.example.com
  • If delegating to another Identity Provider, the authority value is a bare domain name of the target IdP.

Many of these can be tested automatically with the check_primary_support script from the Persona codebase.

For use in production, the SSL certificate must be signed by a trusted CA. For Persona, the list of trusted CAs is dervied from Firefox's certificate bundle. As an example, you can download Persona's bundle from June 2012.

You can use a self-signed certificate for development and testing in pre-production environments.

Your Development Server

For ease of development, it helps to have 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.

Persona JavaScript Libraries

For login to work, both the website you're logging into and your IdP must load the Persona JavaScript libraries, 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.

Debugging Tips

Use Several Browsers

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!

Use the Persona WSAPI and Testing Scripts

Does Persona think your domain is an Identity Provider? Find out by using https://login.persona.org/wsapi/address_info?email=user@example.com.

The check_primary_support script from the Persona codebase can automatically diagnose many misconfigurations.

Revision Source

<h2>Development Tips for Identity Providers</h2>
<h3>Use Responsive Design Techniques</h3>
<p>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.</p>
<h3>Generating Keys</h3>
<p>To generate a keypair suitable for use with Persona, you can use the <a 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 href="https://github.com/mozilla/jwcrypto" title="https://github.com/mozilla/jwcrypto">jwcrypto</a>.</p>
<h3>Serving the Support Document</h3>
<p>To be recognized as an Identity Provider, your domain must publish a support document at <code>/.well-known/browserid</code>. Be sure to review <a href="https://developer.mozilla.org/en-US/docs/BrowserID/.well-known-browserid" title="https://developer.mozilla.org/en-US/docs/BrowserID/.well-known-browserid">its documentation</a>.</p>
<p>In particular, 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 hosted on on the bare domain itself, not a subdomain. For example: <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>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">check_primary_support script from the Persona</a> codebase<strong>.</strong></p>
<p>For use in production, the SSL certificate must be signed by a trusted CA. For Persona, the list of trusted CAs is dervied from Firefox's certificate bundle. As an example, you can download <a href="/@api/deki/files/6289/=cacert.pem" title="/@api/deki/files/6289/=cacert.pem">Persona's bundle from June 2012</a>.</p>
<p>You can use a self-signed certificate for development and testing in pre-production environments.</p>
<h3>Your Development Server</h3>
<p>For ease of development, it helps to have 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>.</p>
<p>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>Persona JavaScript Libraries</h3>
<p>For login to work, both the website you're logging into and your IdP must load the Persona JavaScript libraries, <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>
<h2>Debugging Tips</h2>
<h3>Use Several Browsers</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>Use the Persona WSAPI and Testing Scripts</h3>
<p>Does Persona think your domain is an Identity Provider? Find out 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>.</p>
<p>The <code><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">check_primary_support</a></code><span class="external link-https"> script from the Persona</span> codebase<strong> </strong>can automatically diagnose many misconfigurations.</p>
Revert to this revision