Introduction to Firefox Accounts

Firefox Accounts (FxA) is an identity provider that provides authentication and user profile data for Mozilla cloud services.  We are also exploring the possibility of allowing non-Mozilla services to delegate authentication to Firefox Accounts.

Creating a Firefox Account requires a user to give us a pre-existing email address and choose a password. The user must verify their email address via an email link sent to the email address she provided. The user will not be able to login to attached services prior to verifying her email address. 

To login to an existing Firefox Account, the user must provide the email address and password given during account creation. If the user forgets her password, she can reset via an email link sent to the email address given during account creation. 

All new relying services should integrate with Firefox Accounts via the OAuth 2.0 API.  There is also a legacy API based on the BrowserID protocol, which is available only in some Firefox user agents and is not recommended for new applications.

OAuth 2.0 API

The OAuth 2.0 API is the preferred method of integrating with Firefox Accounts.  It is built on open standards, is available across all platforms, and gives relying services access to user profile data.  To delegate authentication to Firefox Accounts in this manner, you will first need to register for OAuth relier credentials, then add support for a HTTP redirection-based login flow to your service.

Becoming a Firefox Accounts relier

All reliers need to register the following information with Firefox Accounts:

• name - a user friendly name for your service, e.g., "Firefox Marketplace".
• redirect_uri - a HTTPS endpoint on your service, to which we can return the user after authentication has completed.

In return, your service will be allocated a set of OAuth client credentials:

• client_id - an 8 byte hex encoded client identifier for your service. This value is not secret.
• client_secret - a 32 byte hex encoded secret for your service to authenticate itself to the back end FxA OAuth service. This value is secret. Despite its name, this value should never be stored on or given to untrusted client code on users' machines. It should only be used from the service's backend machines to access authenticated API endpoints on the Firefox Accounts OAuth server (e.g., https://github.com/mozilla/fxa-oauth-server/blob/master/docs/api.md#post-v1token).

For development purposes you can use the Firefox Accounts OAuth Credential Management dashboard to provision relier credentials.  Our development environments support "127.0.0.1" and "localhost" as valid "redirectUri" values to ease local development.

Registration of new production reliers is currently a manual process.  Send an email to [email protected] to inform us of your desire to be a relying service, and include the desired name and redirect_uri.  We will work with you to provision client credentials, possibly with multiple versions for different environments (e.g., production, development, etc.):

Note that the client_secret is your responsibility to keep safe. If you lose it, we have no way to recover it, and it will be necessary to issue you a new secret. 

We also recommend that you subscribe to the Firefox Accounts notices mailing list, a low-traffic list that is used to publish important feature updates and security information.

Authenticating with Firefox Accounts

Endpoint Discovery

Given the URL of the Firefox Accounts server, reliers should fetch the OpenID Connect Discovery Document from /.well-known/openid-configuration.  This will return a JSON document with all the endpoint URLs necessary to complete the login flow.  In particular it will contain:

• "authorization_endpoint": the URL to which the client should be directed to begin the authentication flow
• "token_endpoint": the URL at which an OAuth access code can be exchanged for an access token
• "userinfo_endpoint": the URL at which additional user profile data can be obtained

Initiating login

1. Establish a session with the client. This session is between the relying service (i.e., your server) and the client wishing to authenticate itself. The implementation details of this session are up to the relying service, e.g., it could use cookies.
2. Provide the OAuth parameters to the client. These parameters include:
   • client_id - the 8 byte hex encoded client identifier for your relying service established during the provisioning of your service with the FxA team
   • redirect_uri - the redirect_uri you gave the FxA team during the provisioning of your service
   • scope - the requested scope of FxA user data or API access. Currently, only profile and related sub-scopes (e.g., profile:email) are supported.
   • state - an alphanumeric value created by the relying service and associated with client's session. It's up to the relying service how this can be used, but it's primary and recommended purpose is to prevent forgery attacks.
3. Navigate the user's client to the FxA OAuth authorization endpoint.  This URL should come from the "authorization_endpoint" key in the discovery document, and the request must include URL query parameters for the service's client_id and a state value. Refer to the FxA OAuth documentation for further information about this step and optional parameters.

Authenticating the user

After navigating the user's client to the authorization endpoint, the user will be asked to authenticate with her Firefox account or create an account if she doesn't have one:

Redirect back to the relying service

After the user authenticates herself, Firefox Accounts transfers control back to the relying service. On the Web, this happens by redirecting the user's browser back to the redirect_uri endpoint provisioned for the relier. The following information will be provided in the query parameters:

• client_id - the 8 byte hex encoded client identifier for your relying service
• state - the state value provided by the relying service when it navigated the user's client to the FxA OAuth authorization endpoint
• code - an alphanumeric string that the relying service can exchange for an Firefox Accounts OAuth 2.0 access token for the user. A code typically has a lifetime of 15 minutes.

The relying service should make the following security checks:

• Verify the client_id in the redirect request matches its own client_id.
• Verify the state in the redirect request matches the state value previously associated with the client session.

A failure in either of these verifications indicates a security error and the relying service should re-start the login flow. If the relying service receives one of these requests when the client session is already associated with a FxA user, it should be ignored.

Obtaining an OAuth access token

If the above security checks pass, the relying service can proceed to exchange the code provided in the redirect from Firefox Accounts for an OAuth token for the user. This must be done from the relying service's backend server and not from untrusted client code. The service can exchange the code using the "token_endpoint" URL from the discovery document. Refer to the linked documentation for further details. 

Accessing profile data

The access token can now be used to fetch the user's profile data.  Make a GET request to the "userinfo_endpoint" URL obtained from the discovery document, passing the access in the Authorization header as a bearer token.  The response will be a JSON document which may include the following fields:

• uid:  the user's opaque, stable account identifier
• email:  the user's verified email address
• displayName:  the user's preferred human-readable display name
• avater: the URL of the user's profile picture

Some fields may be missing if the appropriate scopes were not requested, or the user declined to share the information.

Security considerations

The FxA OAuth token should only be used as an authentication token to access FxA APIs. It should not:

• be sent to untrusted parties
• be used as a sessioning mechanism to track logged in users.

Relying services should have their own sessioning mechanism independent of FxA OAuth tokens.

Login with the FxA OAuth Javascript library

The simplest way for web based reliers to integrate with Firefox Accounts is with the fxa-relier-client Javascript library. Relying services must first become an FxA OAuth relier. 

Installation

The relier client can be installed via bower, by fetching the latest version from GitHub, or from building from source.

bower

> bower install https://github.com/mozilla/fxa-relier-client.git#release

wget from GitHub

> wget https://raw.githubusercontent.com/mozilla/fxa-relier-client/release/fxa-relier-client.js

Use git to clone the repo

> git clone https://github.com/mozilla/fxa-relier-client.git
> cd fxa-relier-client
> npm install
> grunt build

Include the script in your HTML or JavaScript

The fxa-relier-client can be used as a standalone module or with the RequireJS and Browserify module loaders.

Initiating login

1. Initialize the client
2. Request authentication

3. Trade the returned code for a token, which can be used to access OAuth protected resources.

// initialize the client
var fxaRelierClient = new FxaRelierClient(<client_id>);

// sign up a new user
fxaRelierClient.auth.signUp({
  state: '<state token>',
  redirectUri: '<redirect uri provided when registering>',
  scope: 'profile'
});

// sign in an existing user:
fxaRelierClient.auth.signIn({
  state: '<state token>',
  redirectUri: '<redirect uri provided when registering>',
  scope: 'profile'
});

When either signUp or signIn are called, the user will be redirected to Firefox Accounts to authenticate. Once the user has finished authenticating, they will be redirected to the URL specified in `redirectUri`. See the section "Redirect back to relying service."

Debugging

If the relier library is not working as expected, first look in the browser's developer console to see if any error messages have been displayed. Useful error messages are displayed whenever required parameters are missing or not of the expected format. Next, ensure the API is being called correctly; full API documentation is available on GitHub. If there is still a problem, chat with the folks in the #fxa channel of mozilla.irc.org.

Advanced usage

Pre-fill an email address when calling signIn or signUp

An email can be pre-filled by calling signIn or SignUp with an `email` option.

// suggest the user sign up with the given email address
fxaRelierClient.auth.signUp({
  email: '<email address>',
  state: '<state token>',
  redirectUri: '<redirect uri provided when registering>',
  scope: 'profile'
});

Force the user to authenticate with a given email address

`forceAuth` forces the user to sign in with the given email address. If the email address has not been registered with Firefox Accounts, the user will be unable to register.

// force the user to authenticate as the email provided.
fxaRelierClient.auth.forceAuth({
  email: '<email address>',
  state: '<state token>',
  redirectUri: '<redirect uri provided when registering>',
  scope: 'profile'
});

Lightbox/iframe flow

Instead of redirecting away from the relying site, Firefox Accounts can be displayed in a lightbox. The API is promised base to allow the relying site to be notified when the authentication is complete. When the user has completed authenting, the promise will resolve with a result object that contains three fields: redirect_uri, code, and state. The redirect_uri is the URI the user would have redirected to had the redirect flow been used. code and state are normally POSTed to the server to verify and access protected information. See the section "Redirect back to the relying service" for information on how to complete the OAuth transaction.

// sign up a user using the lightbox.
fxaRelierClient.auth.signUp({
  ui: 'lightbox',
  state: '<state token>',
  redirectUri: '<redirect uri provided when registering>',
  scope: 'profile'
})
.then(function (result) {
  // result contains:
  // redirect_uri - the Uri that would be used if this were the redirect flow
  // code - an OAuth code that can be traded for a token
  // state - state token that should be compared to prevent CSRF attacks.

  // normally, state and code would be sent to your backend to check and trade for
  // an OAuth token which can be used to access protected information.
}, function (err) {
  // A problem occurred.
  // If `err` was generated by Firefox Accounts, it will contain a `reason` field.
  // if `reason==="cancel"`, the user cancelled the signin
});

Testing with Stage, Latest and Stable servers

By default, the fxa-relier-client interacts with production servers. The fxa-relier-client can talk to an alternate server stack by specifying which servers to communicate with in the FxaRelierClient constructor. The list of servers can be found in the section "Firefox Accounts deployments."

Example of how to use the "stable" server

var fxaRelierClient = new FxaRelierClient('<client_id>', {
  contentHost: 'https://stable.dev.lcip.org',
  oauthHost: 'https://oauth-stable.dev.lcip.org/v1'
});

Login with FxAccountsOAuthClient on Firefox Desktop

For chrome code in Firefox Desktop, we provide FxAccountsOAuthClient.jsm for easy integration with FxA OAuth. Relying services must first become an FxA OAuth relier. 

Login with OAuth on Firefox for Android

WIP 

Login with OAuth on Firefox OS

WIP

Legacy BrowserID API

The Firefox Accounts BrowserID is available to chrome code in Firefox Desktop and Firefox of Android. It also available to chrome code and certain restricted applications in Firefox OS. 

Firefox Desktop

Implementation of the BrowserID based FxA API on Desktop: https://github.com/mozilla/gecko-dev/blob/master/services/fxaccounts/FxAccounts.jsm

Firefox for Android

WIP

Firefox OS

Documentation for integrating with FxA on FxOS using the DOM API is here.

Firefox Accounts user data

Firefox Accounts only stores core identity data and associated profile information about users. Firefox Accounts does not store user data specific to relying services. This is responsibility of each relying service. Core identity data stored in Firefox Accounts includes:

• a stable user identifier (uid)
• the user provided email address
• a cryptographically stretched password verifier
• the user's locale provided by her browser during account creation
• optional display name
• optional profile image

​Using a OAuth token

After a relying service has obtained an FxA OAuth access token for a FxA user, it can access Mozilla service APIs that use FxA OAuth. This is largely a work in progress, and we expect the number of APIs that use FxA OAuth will grow and evolve over time.

Firefox Accounts profile server

The Firefox Accounts profile server stores and provides user "profile data". Please refer to the FxA profile server documentation for further information. We provide FxAccountsProfileClient.jsm for easier Firefox Desktop integration.

Firefox Accounts example relier

We created a test relier that delegates authentication to Firefox Accounts called 123done, a simple TODO application. You can use this Web application to create a Firefox Accounts and use it to log in to 123done. Refer to the 123done source code for further details.

Firefox Accounts deployments

URLs for various production, stage, and development deployments.

Production

• FxA OAuth 2.0 endpoint: https://oauth.accounts.firefox.com/v1
• FxA profile endpoint: https://profile.accounts.firefox.com/v1
• FxA content (UI) server: https://accounts.firefox.com
• FxA authentication server: https://api.accounts.firefox.com/v1
• FxA example relier: https://123done-prod.dev.lcip.org

Stage

• FxA OAuth 2.0 endpoint: https://oauth.stage.mozaws.net/v1
• FxA profile endpoint: https://profile.stage.mozaws.net/v1
• FxA content (UI) server: https://accounts.stage.mozaws.net
• FxA authentication server: https://api-accounts.stage.mozaws.net/v1
• FxA example relier: https://123done-stage.dev.lcip.org

Stable development (production clone)

• FxA OAuth 2.0 endpoint: https://oauth-stable.dev.lcip.org/v1
• FxA OAuth 2.0 management console (login requires @mozilla.com email): https://oauth-stable.dev.lcip.org/console
• FxA profile endpoint: https://stable.dev.lcip.org/profile/v1
• FxA content (UI) server: https://stable.dev.lcip.org
• FxA authentication server: https://stable.dev.lcip.org/auth/v1
• FxA example relier: https://123done-stable.dev.lcip.org

Latest development (updated continuously from master)

• FxA OAuth 2.0 endpoint: https://oauth-latest.dev.lcip.org/v1
• FxA OAuth 2.0 management console (login requires @mozilla.com email): https://oauth-latest.dev.lcip.org/console
• FxA profile endpoint: https://latest.dev.lcip.org/profile/v1
• FxA content (UI) server: https://latest.dev.lcip.org
• FxA authentication server: https://latest.dev.lcip.org/auth/v1
• FxA example relier: https://123done-latest.dev.lcip.org
• Add this user.js file to your profile directory to configure Firefox Sync with this environment

Services that use Firefox Accounts

Below is a list of current and future Mozilla services that delegate authentication to Firefox Accounts.

Current

• Firefox Sync (since Firefox 29)
• Find My Device
• Firefox Marketplace
• addons.mozilla.org
• Loop (Firefox Hello)

Contact

• Dev list: [email protected]
• IRC: #fxa

Additional resources

• APIs attached to Firefox Accounts
• Original FxA OAuth design document
• FxA OAuth 2.0 API docs
• FxA OAuth server codebase
• OAuth 2.0 RFC 6749
• Handling Mozilla Security Bugs