User Flow

Here’s the proposed two-step flow (with Browser ID):

1. the client trades a browser id assertion for an Auth token and corresponding secret
2. the client uses the auth token to sign subsequent requests using MAC Access Auth.

Getting an Auth token:

Calling the Service:

Detailed steps:

• the client requests a token, giving its browser id assertion [1]:

  GET /1.0/sync/request_token HTTP/1.1
  Host: token.services.mozilla.com
  Authorization: Browser-ID <assertion>
  

• the Login Server checks the browser id assertion [2] this step will be done locally without calling an external browserid server – but this could potentially happen (we can use PyBrowserID + use the BID.org certificate)

• the Login Server asks the Users DB if the user is already allocated to a Node [3]

• If the user is not allocated to a Node, the Login Server asks a new one to the Node Assignment Server [4]

• the Login Server creates a response with an Auth Token and corresponding Token Secret [5] and sends it back to the user.

  The Auth Token contains the user id and a timestamp, and is signed using the Signing Secret. The Token Secret is derived from the Master Secret and Auth Token using HKDF.

  It also adds the Node url in the response under api_endpoint [6]

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {'id': <token>,
   'secret': <derived-secret>,
   'uid': 12345,
   'api_endpoint': 'https://example.com/app/1.0/users/12345',
  }
  

• the client saves the node location and macauth parameters to use in subsequent requests. [6]

• for each subsequent request to the Service, the client calculates a special Authorization header using MAC Access Auth [7] and sends the request to the allocated node location [8]:

  POST /request HTTP/1.1
  Host: some.node.services.mozilla.com
  Authorization: MAC id=<auth-token>
                     ts="137131201",   (client timestamp)
                     nonce="7d8f3e4a",
                     mac="bYT5CMsGcbgUdFHObYMEfcx6bsw="
  

• the node uses the Signing Secret to validate the Auth Token [9]. If invalid or expired then the node returns a 401

• the node calculates the Token Secret from its Master Secret and the Auth Token, and checks whether the signature in the Authorization header is valid [10]. If it’s an invalid then the node returns a 401

• the node processes the request as defined by the Service [11]