DjaoApp supports the three methods of authentication that are typically found in Web services: Cookies, JSON Web Tokens and API Keys. In the following sections, we will see how to authenticate to the service, on the command line, through the different methods.

Cookies

To authenticate with an HTTP cookie, you will first need to login with a username and password. This will create an HTTP Cookie that is sent back to your browser.

Because browsers send HTTP Cookies with every request to the domain they came from, a lot of attention needs to be dedicated to prevent Cross Site Request Forgery (CSRF). DjaoDjin is using CSRF tokens as a mitigation solution. You will thus need to GET the login page, retrieve the CSRF tokens, and POST to the page, setting the appropriate headers.

On the command line, it looks like:


$ curl -v https://mysitedjaoapp.com/login/ | grep csrfmiddlewaretoken
...
< Set-Cookie: csrftoken=csrftoken_value;  expires= ...
...
<input type="hidden" name="csrfmiddlewaretoken" value="csrfmiddlewaretoken-value">
...
        

Note csrftoken_value and csrfmiddlewaretoken-value, you will need them for the POST phase as such:


$ curl -v -H 'Referer: https://mysitedjaoapp.com/login/' --cookie "csrftoken=csrftoken_value" -d "csrfmiddlewaretoken=csrfmiddlewaretoken-value&username=my-username&password=my-password" https://mysitedjaoapp.com/login/
...
< Set-Cookie: sessionid=sessionid-value; expires=...
        

Armed with a sessionid-value, we can now authenticate with the API.

To validate the sessionid works, we are going to fetch the user profile of the authenticated user. On the command line, this looks like:


$ curl -v --cookie "sessionid=sessionid-value" https://mysitedjaoapp.com/api/users/my-username/
        

JSON Web Tokens

To authenticate with a JSON Web Token, you will first need to create a token by calling /api/auth/ with a username and password. The call will return a token you can subsequently use to authenticate with the service.

On the command line, it looks like:


$ curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username":"my-username","password":"my-password"}' https://mysitedjaoapp.com/api/auth/
{"token":"token-value"}
        

Note token-value. We can now use it to fetch the user profile of the authenticated user. On the command line, this looks like:


$ curl -H 'Accept: application/json' -H 'Authorization: Bearer token-value' https://mysitedjaoapp.com/api/users/my-username/
        

API Keys

To authenticate with an API Key, you will need to create an API key at least once. API Keys are valid until they are revoked. Of course you will need to authenticate with the service first in order to create or rotate a user's API Key (either through a Cookie or a JSON Web Tokens).

For additional security, you will need to pass the password of the authenticated user in order to successfully create or rotate an API Key.

First we are going to create a JSON Web Token (JWT) as above.


$ curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username":"my-username","password":"my-password"}' https://mysitedjaoapp.com/api/auth/
{"token":"token-value"}
        

Armed with a JWT we can now create an API Key for the authenticated user. On the command line, this looks like:


curl -X POST -H 'Authorization: Bearer token-value' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"password":"my-password"}' https://mysitedjaoapp.com/api/auth/
{"secret":"secret-value"}
        

Once we have an API Key, we can start using it directly to authenticate with the service.

To validate the API secret key works, we are going to fetch the user profile of the authenticated user. On the command line, this looks like:


curl -u secret-value: https://mysitedjaoapp.com/api/users/my-username/