Identity/FirefoxAccount

A Firefox Account lets Alice log into Firefox (desktop, mobile, or Firefox OS) with one set of credentials. Alice can then:

• access her bookmarks, apps, browser history, etc., and
• use her Firefox Account identity to log into web sites using the Persona protocol

This document describes the technical architecture of Firefox Accounts.

Firefox Account Provider (FXAP)

A Firefox Account Provider (FXAP) is a Persona Identity Provider (IdP) augmented with a few features.

Thus, based on the Persona protocol, a FXAP server:

• is based at a particular domain, e.g. accounts.acme.com
• manages user identities at that domain, e.g. alice@accounts.acme.com
• publishes a Persona IdP declaration, e.g. https://accounts.acme.com/.well-known/browserid, including
  • an authentication endpoint
  • a provisioning endpoint

In addition, in its .well-known declaration, a FXAP server includes an indication of the authentication protocol it supports, and an endpoint for services discovery:

    {
      ....
      "authenticationProtocol": "srp",
      "authenticationProtocolEndpoint": "/auth",
      "serviceDiscovery": "/services"
    }

Authentication Protocol

The FXAP authentication protocol we support out of the gate is Secure Remote Password (SRP). SRP uses a shared password to generate a shared session key. That key can then be used to sign subsequent requests.

The SRP login protocol consists of one roundtrip to establish the shared key, and another roundtrip to verify that the two parties share the right key. This can easily be modeled with two HTTP messages:

    POST /auth/srp_inititiate
    identity={identity}&A={A}&expiration={numSeconds}&clientName={clientName}

The identity parameter should be in the form of an email address, as per the Persona protocol, for which this FXAP server has authority.

The expiration parameter indicates how long a session the client is requesting. A value of "0" means a forever session (until the key is explicitly invalidated, of course.) clientName indicates a user-understandable name for the client, so that the user can later see which machines are enabled, and disable them from a remote machine.

The server responds with cryptographic parameters s and B, as well as metadata that the client can use to optimize its use of the server:

    {
      "s": "...",
      "B": "...",
      "keyId": "...",
      "expiresAt": <timestamp>
    }

The client can then compute the shared key K, use keyId to indicate to the server which key to use for verification, then use MAC Auth to sign subsequent requests.

To verify that the keys are the same, there is one more request:

    POST /auth/srp_verify
    keyId={keyId}&M1={M1}

to which the server responds:

    {"M2": "..."}

Listing Authorized Clients

An authorized client can list other authorized clients:

    GET /auth/clients

and receive:

    {"clients" : [
       {"clientName": "...", "keyId": "...", "expiresAt": ...},
       ...
    ]}

Obtaining Certs

Once a session is authenticated, the client may ask for a certificate:

    POST /auth/generate_certificate
    identity={identity}&duration={numSeconds}&purpose={purpose}&publicKey={serializedPublicKey}

Invalidating Key

A key K identified by keyId can be invalidated, i.e. logged out:

    POST /auth/invalidate_key
    keyId={keyId}

The keyId parameter is redundant with the MAC Auth header, but that's so the protocol is more RESTful.

Account Creation Protocol

Accounts can be created automatically using the account creation protocol. It seems like the right thing [TO BE CHECKED] to have the server pick the salt, so that the client doesn't decide everything (and thus provide an avenue for replay):

    POST /auth/account_create
    identity={identity}

to which the server responds:

    {"s": "..."}

and the client completes:

    POST /auth/account_create_2
    identity={identity}&verifier={verifier}

Two-Factor Authentication

FXAP servers should implement two-factor auth. This section will document how to tweak the above protocols accordingly.

End-to-End User Data Encryption

Some services may wish to encrypt their content in a way that depends on the user's passphrase. We have explored these ideas with /Identity/CryptoIdeas/02-Recoverable-Keywrapping.