mozilla

Revision 478101 of The navigator.id API

  • Revision slug: Mozilla/Persona/The_navigator.id_API
  • Revision title: The navigator.id API
  • Revision id: 478101
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

For full details about the navigator.id API, refer to its reference pages.

With Persona, a website asks the user to provide an "assertion", which is a digitally signed email address. By verifying the signature, the site can be assured that the user really does control the address in question. The site can then use this email address as an identifier for that user.

To ask for an assertion, the website calls a JavaScript API defined by the id object, which is a member of the global navigator object.

In future we expect the id object to be built into the browser, but at the moment it isn't, so sites using Persona need to include the polyfill library hosted at https://login.persona.org/include.js in their pages. After that, they can work as if id is just a built-in member of navigator.

There are two current versions of the API: the "Callback API", and the newer "Observer API".

The Callback API

The Callback API consists of a single function, get(). It takes two arguments:

  • an options object that mostly customizes the dialog presented to users: allowng a website to link to its privacy policy, to set background color or include an icon, for example
  • a callback function that will be called back with a signed assertion if the user successfully authenticates to their Identity Provider

 

var signin = document.getElementById('sign-in');
signin.addEventListener("click", getAssertion, false);

// get an assertion
function getAssertion() {
  navigator.id.get(verifyAssertion, {backgroundColor: "#606B72", siteName: "My Example Site"});
}

// send the assertion to the server for verification
function verifyAssertion(assertion) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "/verify", true);
  var param = "assertion="+assertion;
  xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  xhr.setRequestHeader("Content-length", param.length);
  xhr.setRequestHeader("Connection", "close");
  xhr.send(param);
  xhr.onload = handleVerificationResponse(xhr);
}

Advantages of the Callback API

The Observer API

Advantages of the Observer API

The Observer API offers two main advantages over the Callback API: a better first-time sign-in experience for some users, and session management.

First-time sign-in experience

The first time a user signs in using Persona, they may need to create a Persona account. This will happen if they haven't used Persona before and if their email provider does not support Persona. In this case they will be invited to create an account using the fallback provider. After creating an account, if they use the Callback API, they will not be automatically redirected to the original website to finish signing in: they will have to navigate back to the original website.

Session Management

The Callback API doesn't provide any support for session management: this is something the website needs to provide.

Revision Source

<div class="note">
  For full details about the <code>navigator.id</code> API, refer to its <a href="/en-US/docs/Web/API/navigator.id">reference pages</a>.</div>
<p>With Persona, a website asks the user to provide an "assertion", which is a digitally signed email address. By verifying the signature, the site can be assured that the user really does control the address in question. The site can then use this email address as an identifier for that user.</p>
<p>To ask for an assertion, the website calls a JavaScript API defined by the <code>id</code> object, which is a member of the global <a href="/en-US/docs/Web/API/Navigator"><code>navigator</code></a> object.</p>
<p>In future we expect the <code>id</code> object to be built into the browser, but at the moment it isn't, so sites using Persona need to include the polyfill library hosted at <a class="external link-https" href="https://login.persona.org/include.js" title="https://login.persona.org/include.js">https://login.persona.org/include.js</a> in their pages. After that, they can work as if <code>id</code> is just a built-in member of <code>navigator</code>.</p>
<p>There are two current versions of the API: the "Callback API", and the newer "Observer API".</p>
<h2>The Callback API</h2>
<p>The <a href="/en-US/docs/Web/API/navigator.id#CallbackMethods">Callback API</a> consists of a single function, <a href="/en-US/docs/Web/API/navigator.id.get"><code>get()</code></a>. It takes two arguments:</p>
<ul>
  <li>an options object that mostly customizes the dialog presented to users: allowng a website to link to its privacy policy, to set background color or include an icon, for example</li>
  <li>a callback function that will be called back with a signed assertion if the user successfully authenticates to their Identity Provider</li>
</ul>
<p>&nbsp;</p>
<pre class="brush: js">
var signin = document.getElementById('sign-in');
signin.addEventListener("click", getAssertion, false);

// get an assertion
function getAssertion() {
  navigator.id.get(verifyAssertion, {backgroundColor: "#606B72", siteName: "My Example Site"});
}

// send the assertion to the server for verification
function verifyAssertion(assertion) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "/verify", true);
  var param = "assertion="+assertion;
  xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  xhr.setRequestHeader("Content-length", param.length);
  xhr.setRequestHeader("Connection", "close");
  xhr.send(param);
  xhr.onload = handleVerificationResponse(xhr);
}</pre>
<h3>Advantages of the Callback API</h3>
<h2>The Observer API</h2>
<h3>Advantages of the Observer API</h3>
<p>The Observer API offers two main advantages over the Callback API: a better first-time sign-in experience for some users, and session management.</p>
<h4>First-time sign-in experience</h4>
<p>The first time a user signs in using Persona, they may need to create a Persona account. This will happen if they haven't used Persona before and if their email provider does not support Persona. In this case they will be invited to create an account using the <a href="/en-US/docs/Persona/Bootstrapping_Persona">fallback provider</a>. After creating an account, if they use the Callback API, they <em>will not</em> be automatically redirected to the original website to finish signing in: they will have to navigate back to the original website.</p>
<h4>Session Management</h4>
<p>The Callback API doesn't provide any support for session management: this is something the website needs to provide.</p>
Revert to this revision