Firefox Accounts

Firefox Accounts (FxA) is an identity provider that provides authentication and user profile data for Mozilla cloud services. Longer term we envision that non-Mozilla services and applications will also be able 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. 

The way relying services integrate with Firefox Accounts differs based on the platform, but we hope to make this more uniform over time. There are two ways relying services can integrate with Firefox Accounts:

• a OAuth 2.0 API (available on the Web)
• a BrowserID based API (available only in our user agents)

Firefox Accounts OAuth 2.0 API

Going forward, our OAuth 2.0 API will be the preferred method of integrating with Firefox Accounts, primary because it gives relying services access to user profile and other data and we anticipate it will be available on all platforms. This will enable us to have a common, uniform way for relying services to integrate with Firefox Accounts.

Becoming a Firefox Accounts OAuth relier

If you're a Mozilla service, email [email protected] to inform us of your desire to be a relying service, we'll be in touch. You will need to provide us with the following information:

• name - a user friendly name for your service, e.g., "Firefox Marketplace".
• redirect_uri - a GET HTTPS endpoint on your service that we can transfer control back to after user authentication has completed.

We will respond with your client information, possibly with multiple versions for different environments (e.g., production, development, etc.):

• 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.
• redirect_uri - the redirect_uri you gave the FxA team previously above

For development purposes you can use the Firefox Accounts OAuth Credential Management dashboard to provision credentials. However, we currently have no automated way to provision relying services in production. 

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. 

Login with the FxA OAuth HTTP API

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
   • oauth_uri - the FxA OAuth endpoint. In production, this is https://oauth.accounts.firefox.com/v1. For self-hosted, dev, or staging environments, this will be different.
   • [optional] profile_uri -  the FxA Profile endpoint. In production, this is https://profile.accounts.firefox.com/v1. For self-hosted, dev, or staging environments, this will be different.
   • [optional] content_uri - the origin of FxA login page. In production, this is https://accounts.firefox.com. For self-hosted, dev, or staging environments, this will be different. This is only required by the Firefox Desktop OAuth client (available in chrome) and can be omitted in Web contexts.
   • 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. In production, this is https://oauth.accounts.firefox.com/v1/authorization. This 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 token for the user with the FxA OAuth /v1/token endpoint. 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 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 FxA OAuth /v1/token endpoint. Refer to the linked documentation for further details. 

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, Nightly 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

Firefox Accounts 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

Associated user profile data is a work in progress, but includes:

• profile image

​Using a OAuth token

After a relying service has obtained an FxA OAuth 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". Currently, a user profile consists of a stable user identifier (uid) and email address, but in the future we anticipate it will include an avatar image, screen name, phone number, preferred locale, and other information. 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

Nightly development (updated nightly from master)

• FxA OAuth 2.0 endpoint: https://oauth-nightly.dev.lcip.org/v1
• FxA profile endpoint: https://nightly.dev.lcip.org/profile/v1
• FxA content (UI) server: https://nightly.dev.lcip.org
• FxA authentication server: https://nightly.dev.lcip.org/auth/v1
• FxA example relier: https://123done-nightly.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
• Loop

Future

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