IdP Development Tips

  • Revision slug: BrowserID/Primary/Developer_tips
  • Revision title: Developer tips
  • Revision id: 233719
  • Created:
  • Creator: petef
  • Is current revision? No
  • Comment 26 words added

Revision Content

Primary IdP Developer Tips and Tricks

If you're a developer for an email or identity providing service, you'll want to build out support to be a BrowserID primary. Here are some tips and tricks:

  • Your development server must be on the public internet to test against dev.diresworb.org
    • If you run a local instance (see below) of BrowserID, you can also have your primary be local
  • The Primary you're building as well as any "client websites" must all point to the same BrowserID environment. Examples:
    • Use myfavoritebeer.org (as client website) and point your script tags at browserid.org
    • Use beta.myfavoritebeer.org and point your script tags at diresworb.org, this is the preferred method for staging environments
    • Use dev.myfavoritebeer and point your script tags at dev.diresworb.org, this is the preferred method for development environments
    • Use 127.0.0.1:10001 and point your script tags to 127.0.0.1:10002
    • This is true for all scripts: include.js, provisioning_api.js, authentication_api.js
  • When your happy with your development IdP, point it at production BrowserID.
  • Only deploy against BrowserID.org for your production IdP
  • BrowserID requires a valid SSL certificate and HTTPS protocol. You can use a self-signed cert for development by pointing to dev.diresworb.org
    • Production verifies certificates against a list of CAs trusted by Firefox.  As of June 2012, the CA bundle we're using is attached here
  • On myfavoritebeer.org click "Sign In" and enter your email address, where your domain matches the domain of your IdP.
  • Look at JS Console, network traffic, etc in your browser's developer tools for interactions between your primary and BrowserID.org
    • Try this on multiple browsers. The architecture of this system doesn't have great debugging support on any one browser, they all tend to surface different things (due to iframe, postMessage, etc)
    • Expand responses and look at actual response bodies
  • Bug 1205: BrowserID will cache your /.well-known/browserid file
    • If you have anything wrong, it will cache your domain as "secondary"
    • If you have everything right, your public key will be cached. Changing your public key will result in bad signature in cert chain error
  • To check to see if BrowserID considers your system a primary, try curl https://dev.diresworb.org/wsapi/addr...RNAME%40DOMAIN
  • Your testing email addresses must match the IdP domain name. You might use alice@dev.example.com, then alice@stage.example.com, and finally alice@example.com once you went to production.

Debugging by running a local BrowserID.org server

The best way to build your primary is to point it at dev.diresworb.org and use dev.myfavoritebeer.org to test it.

If you wanted to keep everything local to your desktop computer, you could download the source for the BrowserID secondary server.

This option is not recommended, unless you are comfortable with Node.js and grepping around the source.

Basically, you would run a set of Node.js BrowserID services (browserid, verify, dbwriter, etc).

Read the documenation under docs. Grep through the source, but there is a SHIMMED_PRIMARIES environment variable, which you can point to your local server.

Remember, noone externally can see your local BrowserID server. You'll eventually want to run against the official production browserid.org server.

Revision Source

<h2>Primary IdP Developer Tips and Tricks</h2>
<p>If you're a developer for an email or identity providing service, you'll want to build out support to be a BrowserID primary. Here are some tips and tricks:</p>
<ul> <li>Your development server must be on the public internet to test against dev.diresworb.org <ul> <li>If you run a local instance (see below) of BrowserID, you can also have your primary be local</li> </ul> </li> <li>The Primary you're building as well as any "client websites" must all point to the same BrowserID environment. Examples: <ul> <li>Use myfavoritebeer.org (as client website) and point your script tags at browserid.org</li> <li>Use beta.myfavoritebeer.org and point your script tags at diresworb.org, <strong>this is the preferred method for staging environments</strong></li> <li>Use dev.myfavoritebeer and point your script tags at dev.diresworb.org, <strong>this is the preferred method for development environments</strong></li> <li>Use 127.0.0.1:10001 and point your script tags to 127.0.0.1:10002</li> <li>This is true for all scripts: include.js, provisioning_api.js, authentication_api.js</li> </ul> </li> <li>When your happy with your development IdP, point it at production BrowserID.</li> <li>Only deploy against BrowserID.org for your production IdP</li> <li>BrowserID requires a valid SSL certificate and HTTPS protocol. You can use a self-signed cert for development by pointing to dev.diresworb.org <ul> <li>Production verifies certificates against a list of CAs trusted by Firefox.  As of June 2012, the CA bundle we're using is attached <a href="/@api/deki/files/6289/=cacert.pem" title="https://developer.mozilla.org/@api/deki/files/6289/=cacert.pem">here</a></li> </ul> </li> <li>On myfavoritebeer.org click "Sign In" and enter your email address, where your domain matches the domain of your IdP.</li> <li>Look at JS Console, network traffic, etc in your browser's developer tools for interactions between your primary and BrowserID.org <ul> <li>Try this on multiple browsers. The architecture of this system doesn't have great debugging support on any one browser, they all tend to surface different things (due to iframe, postMessage, etc)</li> <li>Expand responses and look at actual response bodies</li> </ul> </li> <li><a class="link-https" href="https://github.com/mozilla/browserid/issues/1205" title="https://github.com/mozilla/browserid/issues/1205">Bug 1205:</a> BrowserID will cache your /.well-known/browserid file <ul> <li>If you have anything wrong, it will cache your domain as "secondary"</li> <li>If you have everything right, your public key will be cached. Changing your public key will result in bad signature in cert chain error</li> </ul> </li> <li>To check to see if BrowserID considers your system a primary, try <code>curl <a class=" link-https" href="https://dev.diresworb.org/wsapi/address_info?email=USERNAME%40DOMAIN" rel="freelink">https://dev.diresworb.org/wsapi/addr...RNAME%40DOMAIN</a></code></li> <li> <div>Your testing email addresses must match the IdP domain name. You might use <a class=" link-mailto" href="mailto:alice@dev.example.com" rel="freelink">alice@dev.example.com</a>, then <a class=" link-mailto" href="mailto:alice@stage.example.com" rel="freelink">alice@stage.example.com</a>, and finally <a class=" link-mailto" href="mailto:alice@example.com" rel="freelink">alice@example.com</a> once you went to production.</div> </li>
</ul>
<h2>Debugging by running a local BrowserID.org server</h2>
<p>The <strong>best way to build your primary</strong> is to <strong>point it at dev.diresworb.org and use dev.myfavoritebeer.org</strong> to test it.</p>
<p>If you wanted to keep everything local to your desktop computer, you could download the <a class="link-https" href="https://github.com/mozilla/browserid" title="https://github.com/mozilla/browserid">source for the BrowserID secondary server</a>.</p>
<p><strong>This option is</strong> <strong>not recommended</strong>, unless you are comfortable with Node.js and grepping around the source.</p>
<p>Basically, you would run a set of Node.js BrowserID services (browserid, verify, dbwriter, etc).</p>
<p>Read the documenation under docs. Grep through the source, but there is a <code>SHIMMED_PRIMARIES</code> environment variable, which you can point to your local server.</p>
<p>Remember, noone externally can see your local BrowserID server. You'll eventually want to run against the official production browserid.org server.</p>
Revert to this revision