Overview

Firefox Accounts is an identity provider. The primary goal of Firefox Accounts is to provide user identities for an ecosystem of attached services.

The concerns of Firefox Accounts include:

Provide a way for users to identify themselves (currently email address)
Provide a way for users to authenticate themselves (currently password)
Provide a stable user identifier (i.e. uid)
Provide a way for relying services to delegate authentication concerns to Firefox Accounts
Host core associated user profile data (e.g., profile image, screen name, etc) and provide this data to its relying services

The concerns of Firefox Accounts do not include storing application or user data specific to each relying service. This is the responsibility of each relying service. Firefox Accounts only will host user data that is relevant to at least 2 (but hopefully more) relying services (e.g., a profile image). In the future, we may build a service that allow "serverless" applications to store user data, but this would be separate service and not Firefox Accounts.

Integrating with FxA on the Web and Desktop Firefox

Web applications (i.e., assuming no additional client support) and services in Desktop Firefox integrate with Firefox Accounts via our OAuth 2.0 API. Firefox Accounts OAuth integration is currently limited to Mozilla relying services. We have the intention to, in the future, allow third-party services to delegate authentication to Firefox Accounts, but have no committed timeline for this.

Contact the FxA team to obtain OAuth credentials

If you're not a Mozilla service, please be informed you cannot be a relying service at this time. If you're a Mozilla service, email dev-fxacct@mozilla.org to inform us of you're desire to be a relying service, we'll be in touch.

You need to provide us with the following information:

name: a user friendly name of your service
redirect_uri: a GET HTTPS endpoint on your service that we can transfer control back to after user authentication has completed
(optional) image_uri: a URI of a user friendly image or icon for your service (Note: this is currently not used and underspecified)

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 FxA OAuth endpoints (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

We currently have no automated way to provision relying services, and it will be handled out of band. 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.

Using the FxA OAuth HTTP API directly

Firefox Accounts provides a OAuth 2.0 HTTP API. Reliers can use this to build a redirect or popup based FxA login flow. Currently, using this API directly is the only integration choice for Web applications. Longer term we recommend using the below Javascript client libraries, but these are still a work in progress. The recommended steps for using the HTTP API directly are:

1) Establish a session 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) Have the client fetch the FxA OAuth configuration/parameters from the relying service. This configuration includes:

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 relying 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.
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.
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 Desktop Firefox OAuth client 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.

For example,

{
    "client_id": "dcdb5ae7add825d3", // id for the relying service
    "oauth_uri": "https://oauth.accounts.firefox.com/v1", // OAuth endpoint
    "profile_uri": "https://profile.accounts.firefox.com/v1", // only required if the client needs to contact the FxA profile server directly with the resulting OAuth token
    "content_uri": "https://accounts.firefox.com", // only required for the Desktop client
    "scope": "profile", // requested scope of user data
    "state": "2d37b565fc349d633e57291cf03ac69180f5541bbf06d9de78e373ed43fb62cf"
}

3) Navigate the user's client to GET /v1/authorization on the FxA OAuth server. This will direct the user to a FxA login page.

4) Firefox Accounts will navigate the user's client back to the relying service's redirect_uri after the FxA login flow completes. This request will include some additional query parameters:

client_id: the 8 byte hex encoded client identifier for your relying service
state: the state value provided by the relying service during GET /v1/authorization in step 3.
code: a string that the relying will trade with the FxA OAuth /v1/token endpoint to obtain an FxA OAuth 2.0 token for the authenticated user. A code typically has a lifetime of 15 minutes.

Then, the relying service should:

Verify the given client_id matches its own client_id.
Verify the given state 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.

If both validate, continue to the next step.

5) Exchange the received code for an FxA OAuth token for the user. This is done with the POST /v1/token endpoint, and requires the relying service's client_id and client_secret in addition to the code it received.

Using the FxA OAuth Javascript client library for Web applications

Using the FxA OAuth Javascript client library for Firefox Desktop services

Integrating with FxA on Firefox for Android

Integrating with Firefox Accounts on Firefox OS