IdentityManager.request()

Summary

This function enables a web site to use Persona to authenticate its users. It must be invoked from within a click handler. For example, you should call it when a user clicks your "log in with Persona" button.

When invoked, navigator.id.request() will ask the user to choose an email address to sign in with, and may ask the user to authenticate with their identity provider if the user's certificate has expired. It will then generate a signed assertion containing the user's email address and pass that assertion to the onlogin callback registered with navigator.id.watch().

This function must be used in conjunction with navigator.id.watch().

Syntax

navigator.id.request();
navigator.id.request({siteName: 'Example Site', siteLogo: '/logo.png'});
navigator.id.request({termsOfService: '/tos.html', privacyPolicy: '/privacy.html'});

Parameters

backgroundColor Optional

A hexadecimal color to use as the login dialog's background. Format: "#rgb" or "#rrggbb".

oncancel Optional

A function that will be invoked if the user refuses to share an identity with the site.

privacyPolicy Optional

Must be served over SSL. The termsOfService parameter must also be provided.

Absolute path or URL to the web site's privacy policy. If provided, then termsOfService must also be provided. When both termsOfService and privacyPolicy are given, the login dialog informs the user that, by continuing, "you confirm that you accept this site's Terms of Use and Privacy Policy." The dialog provides links to the the respective policies.

returnTo Optional

Absolute path to send new users to after they've completed email verification for the first time. The path must begin with '/'. This parameter only affects users who are certified by Mozilla's fallback Identity Provider. This value passed in should be a valid path which could be used to set window.location too.

siteLogo Optional

Must be served over SSL.

Absolute path to an image to show in the login dialog. The path must begin with '/'. Larger images will be scaled down to fit within 100x100 pixels.

siteName Optional

Plain text name of your site to show in the login dialog. Unicode and whitespace are allowed, but markup is not.

termsOfService Optional

Must be served over SSL. The privacyPolicy parameter must also be provided.

Absolute path or URL to the web site's terms of service. If provided, then privacyPolicy must also be provided. When both termsOfService and privacyPolicy are given, the login dialog informs the user that, by continuing, "you confirm that you accept this site's Terms of Use and Privacy Policy." The dialog provides links to the the respective policies.

Example

var signinLink = document.getElementById('signin');
if (signinLink) {
  signinLink.onclick = function(evt) {
    // Requests a signed identity assertion from the user.
    navigator.id.request({
      siteName: 'My Example Site',
      siteLogo: '/logo.png',
      termsOfService: '/tos.html',
      privacyPolicy: '/privacy.html',
      returnTo: '/welcome.html',
      oncancel: function() { alert('user refuses to share identity.'); }
    });
  };
}

Specification

Not included in any specification.

See also

• BrowserID
• navigator.id
• navigator.id.watch()
• navigator.id.logout()