== Flow ==
Here's the proposed two-step flow (with Browser ID): # the client trades a browser id assertion for an auth token and corresponding secret# the client uses the auth token to sign subsequent requests using two-legged oauth Getting an auth tokensee http: <pre>Client Login Server BID User DB Node Assignment Server =========================================================================================================== | | | | request token ---- [1] --------->|------> verify --- [2] -->| | | | get node -- [3] ---|------------>|--> lookup | | | |<-- return node | | attribute node --[4]----|-------------|------------------->|--> set node | | | |<-- node |<--- build token [5] | | | keep token <-------- [6] --------| | | | </pre> Calling the service: <pre> Client Service Node============================================================create signed auth header [7] | | call node --------------- [8] ---|---------------->|--> verify token [9] | | verify request signature [10] | |<-- process request [11]get response <-------------------|-----------------|</pre> * the client requests a token, giving its browser id assertion [1] GET /1.0/sync/request_token HTTP/1.1 Host: tokendocs.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 pyvep + 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 ''service_entry'' [6] HTTP/1.1 200 OK Content-Type: application/json {'oauth_consumer_key': <auth-token>, 'oauth_consumer_secret': <token-secret>, 'service_entry': <node> } * the client saves the node location and oauth parameters to use in subsequent requests. [6]* for each subsequent request to the Service, the client calculates a special Authorization header using two-legged OAuth [7] and sends the request to the allocated node location [8] POST /request HTTP/1.1 Host: some.node.services.mozilla.com Authorization: OAuth realm="Example", oauth_consumer_key=<authuser-token> oauth_signature_method="HMAC-SHA1", oauth_timestamp="137131201", (client timestamp) oauth_nonce="7d8f3e4a", oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D" * 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]flow. If it's an invalid then the node returns a 401* the node processes the request as defined by the Service [11]html
== Authorization token ==
