Here’s the proposed two-step flow (with Browser ID):
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]