Protocol Token

The authentication service handles login for the users and hands out token based on identity/user mappings set in the database.

Discussion

To lower the latency of the stack services, a token caching strategy could be deployed. This, however, involves a few steps to work without resulting in an inconsistent state across services. Design suggestions are:

• Invalidate cache based on expiry timestamp. Refreshing tokens independent of user requests leads to potential higher - but predictable - bandwidth consumption.
• Add an event socket to the authentication server which notifies all active servers about the invalidation of a token

Apart from that, it may be beneficial to implement authentication service interface as a regular socket (or domain socket) to remove the overhead of HTTP, which in this case is significant.

Design

The authentication process is outlined below. The stack service represents a generic service from our software stack which requires a valid identity to either map to local ACL, or merely verify that the user is logged into the system.

Oauth2 whitelist

http://auth.adaheads.com/oauth2callback
https://auth.adaheads.com/oauth2callback
http://localhost:8080/token/oauth2callback
http://alice.adaheads.com:4050/token/oauth2callback

Can be managed here.

Create a new token - asynchronously

POST /token/create With the object body: { type : (plain | kerberos | md5), returnURL : <URL>, <credentials> } will create a new token and return it in the body of the reponse. The method will pass-through the supplied credentials to a backend and based on the response generate a token or notify the user of an authentication failure.

Success

The token will be returned in the token field of the body.

Example response.

HTTP status: 200 OK

{
   "status"  : "ok",
   "token"   : <token>
 }

Failure - There is an error in the request body

Example response.

HTTP status: 400 Bad request

{
   "status"      : "bad request",
   "description" : "Invalid, missing or malformed parameters"
 }

Failure - The backend did not validate the user.

Example response

HTTP Status: 403 Forbidden

{
   "status"      : "forbidden",
   "description" : "Authentication failed."
 }

Create a new token - via external provider

GET /token/create With the object body: { type : (oauth2 | opendid), returnURL : URL } will create a new token using by actively redirecting OAuth, OpenID (or other) provider.

Success

The token will be returned via the setToken parameter to the returnURL.

Example response.

HTTP status: 307 Redirect returnURL?setToken=

Failure - There is an error in the request body

Example response.

HTTP status: 400 Bad request

{
   "status"      : "bad request",
   "description" : "Invalid, missing or malformed parameters"
 }

Failure - The backend did not validate the user.

Example response

HTTP Status: 403 Forbidden

{
   "status"      : "forbidden",
   "description" : "Authentication failed."
 }

Retrieving the user associated with a token

GET /token/<token>

Success

The user object associated with the token is returned in the body of the response.

Example response.

HTTP status: 200 OK

{}

Failure - no user is associated with the token.

An empty object is returned, along with a "not found" status.

Example response.

HTTP status: 404 Not found

{}

Validate the existence of a user

GET /token/<token>/validate

This method is a shorter/faster version of the GET /token/<token> method that does not require database interaction.

Success

An empty object is returned along with a success status.

Example response.

HTTP status: 200 OK

{}

Failure - no user is associated with the token.

An empty object is returned, along with a "not found" status.

Example response.

HTTP status: 404 Not found

{}

Invalidate a token

GET /token/<token>/invalidate

Success

An empty object is returned along with a success status.

Example response.

HTTP status: 200 OK

{}

Failure - no user is associated with the token.

An empty object is returned, along with a "not found" status.

Example response.

HTTP status: 404 Not found

{}