Session based REST authentication, CSRF/XSRF protection
Mango 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 v4
- Login URL is now /rest/latest/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/latest/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:<Mango GUID>=<Cookie Name>
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/latest/users/current
Request Method: GET
Request Headers:
Accept:application/json, text/plain, */*
Cookie:node0yg1gfso8xgvIcb2239cmofpy1.node0; Path=/; Domain=.developer.radixiot.app; Secure; HttpOnly; 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.
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/latest/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