Skip to content

0.7 Authentication

Jump to bottom
Kurtis edited this page May 21, 2013 · 17 revisions

Back to 0.7 API

Authentication

Authentication for UDJ is done using a ticket based system.

  1. The user provides the server with their Username and Password.
  2. If the Username and Password correspond to a valid user on the server, the server then issues a ticket.
  3. This ticket is then used in all further communication with the server.

Tickets are important and clients are strongly encourage to protect them as much as possible. A stolen ticket can result in a malicious entity impersonating a user. Server implementations are highly encouraged to invalidate tickets that have not been used recently in order to avoid the "It's an older code, sir, but it checks out." issue.

Endpoints:

/auth

POST

The auth method allows a client to authenticate with the webserver and must be executed before any further communication between the client and the server can take place.

Required JSON object

{
  `username` : username of user to be authenticated,
  `password` : password of user to be authenticated
}

If the username and password combination is valid, the server will return a JSON object containing a ticket hash and the user's assigned id. The parameters should be given as a JSON object:

Example response from the server

{ 
  "ticket_hash" : assigned ticket hash, 
  "user_id" : id 
}

All subsequent requests must be sent with the given ticket in the header like so:

X-Udj-Ticket-Hash: assigned ticket hash

If any API methods that require authentication are called without this ticket in the header, or with an invalid ticket, a HTTP 401 response will be returned. The response'sWWW-Authenticate header will be set to the value ticket-hash.

Ticket's may become invalid at any time.

Errors

  • HTTP 400 - Bad Request - The username and/or password attributes of the required JSON object was/were not supplied
  • HTTP 401 - Unauthorized - The username and password combination is invalid. The WWW-Authenticate header will be set to password.

/fb_auth

POST

This auth method allows a client to authenticate with a UDJ server using Facebook credentials. It is essentially identical to the method described above with two exceptions:

  • Instead of sending a username and password combination the client should send a facebook user_id and valid access_token for that user obtained via the Facebook Login System. The JSON sent should look like:

Required JSON object

 {
   "user_id" : facebook user id,
   "access_token" : access token for the user
 }
  • Instead of responding with an HTTP 401 when a bad username and password combination is provided, an HTTP 401 reaponse will be sent when an invalid user_id and access_token combination are provided. The WWW-Authenticate header will be set to access_token.

Note

The access token provided must be able to obtain the Facebook user's e-mail address. Clients should verify that the provided access token can be used to obtain the user's e-mail address lest the server return with an Http 401 response.

Clone this wiki locally