Session based REST authentication, CSRF/XSRF protection

Mango v3 now uses a stateless double-submission CSRF/XSRF protection mechanism. This means that you can generate the initial XSRF token value on the client side and it is unnecessary to perform an initial request just to get the XSRF-TOKEN cookie value.

If you generate the token value this way you should use a secure (cryptographically strong) random generation method and keep the token secret.

It is still necessary to read the session cookie from the “Set-Cookie” header when logging in and send this back to Mango in the “Cookie” header.

Changes to authentication in Mango v3

  • Login URL is now /rest/v2/login
  • The Login HTTP method is now POST instead of GET
  • Login now sends the username and password as JSON in the request body
    • Username query parameter and password header no longer used
  • CSRF protection uses a stateless double-submit mechanism
    • X-XSRF-TOKEN header value must match the value in the Cookie header

Example login

Request

Request URL: http://localhost:8080/rest/v2/login
Request Method: POST

Request Headers:
Accept:application/json
Content-Length:39
Content-Type:application/json;charset=UTF-8
Cookie:XSRF-TOKEN=74cf354a-e871-48b6-a1c2-bebb93d00120
X-XSRF-TOKEN:74cf354a-e871-48b6-a1c2-bebb93d00120

Request Payload (JSON):
{“username”: "admin", “password”: "admin"}

Response

Response Status Code: 200 OK

Response Headers:
Content-Type:application/json;charset=UTF-8
Set-Cookie:MANGO8080=1lolz85rdcm6w1c5loyzl7y4sc;Path=/;HttpOnly
Set-Cookie:XSRF-TOKEN=072a9aa4-7998-485c-8b53-a7dd7dcbc3e7;Path=/
Response body: User JSON

Example REST call after logging in

Request

Request URL: http://localhost:8080/rest/v1/users/current
Request Method: GET

Request Headers:
Accept:application/json, text/plain, */*
Cookie:MANGO8080=1lolz85rdcm6w1c5loyzl7y4sc; XSRF-TOKEN=072a9aa4-7998-485c-8b53-a7dd7dcbc3e7
X-XSRF-TOKEN:072a9aa4-7998-485c-8b53-a7dd7dcbc3e7

Response

Response Status Code: 200 OK

Response Headers:
Content-Length:410
Content-Type:application/json;charset=UTF-8
Response body: User JSON


 

Token based authentication (JWT)

Token based authentication has been available since Mango 3.3.0. You can create a JWT (JSON web token) authentication token from the users page.

token auth.PNG

Once you have created your token you can use it to access the REST API by putting it into the Authorization header as shown below (note the Bearer prefix and space). No login or XSRF token is necessary.

Request

Request URL: http://localhost:8080/rest/v1/users/current
Request Method: GET

Request Headers:
Accept:application/json, text/plain, */*
Authorization: Bearer eyJhbGciOiJFUzUxMiJ9.eyJzdWIiOiJzdXBlcnZpc29yIiwiZXhwIjoxNTI3MDE2NTgyLCJpZCI6MTkzLCJ2IjoxLCJ0eXAiOiJhdXRoIn0.ALBmRhMt-Ypy2XDwiWFPH-ujWuFOJ6xODC9ixka2dqYuf8c7eh0BgUrKOPeV-Ll0-eP_gQ_K74y91r98QWxYFiV-ALC807LPngvlo8TsgEyDW2rAkRzfwlrB809TvAXLV8zEOQaQhrn2o1uBcY-ETq5ESkfrkLa8VUDZHu3Un_4-Zb9t

Response

Response Status Code: 200 OK

Response Headers:
Content-Length:410
Content-Type:application/json;charset=UTF-8
Response body: User JSON