Login and Authorization Tokens#

The API includes as part of responses a X-CSRFToken response header that is set to the CSRF token, for example to KEMzraBRygy2ZJ7fLuvbfKhAEIPK9D4s. API clients should source the CSRF token from this header.

For background on CSRF, see:

The API also includes as a part of responses a csrftoken cookie containing the CSRF token. This cookie is marked httponly and as such is not readable by browser-based client scripts. API clients should not try to source the CSRF token from this cookie.

The X-CSRFToken response header and csrftoken cookie values are identical.

When performing requests that require CSRF token validation, API clients should follow the general procedure:

  1. Prior to performing the principal request, perform a request to the API and retrieve a CSRF token from the resulting response’s X-CSRFToken response header. The CSRF token remains constant for the duration of a session, so clients could perform this request once per session (post authentication), storing the CSRF token and using it for subsequent requests.

    Clients should also retrieve the csrftoken cookie from the response.

  2. For the primary request, include a X-CSRFToken request header containing the CSRF token as sourced from the response header, as well as the unchanged csrftoken cookie.

    Note

    Cookies must conform to https://tools.ietf.org/html/rfc6265

Example for login:

GET http://localhost:8000/login/

Raw response headers:
Cache-Control: max-age=0
Connection: keep-alive
Content-Encoding: gzip
Content-Language: en-us
Content-Type: text/html; charset=utf-8
Date: Mon, 20 Apr 2015 09:18:47 GMT
Expires: Mon, 20 Apr 2015 09:18:47 GMT
Last-Modified: Mon, 20 Apr 2015 09:18:47 GMT
Server: nginx/1.4.6 (Ubuntu)
Set-Cookie: csrftoken=KEMzraBRygy2ZJ7fLuvbfKhAEIPK9D4s;
 SameSite=Lax;
 httponly;
 Path=/
sessionid=5d1ccc96cbd7e7f290020aaedd64c1b3; httponly; Path=/
sso_login_url=; Path=/
Transfer-Encoding: chunked
Vary: Accept-Encoding, Cookie, Accept-Language, X-CSRFToken
X-CSRFToken: KEMzraBRygy2ZJ7fLuvbfKhAEIPK9D4s

  1. Source the CSRF token from response’s X-CSRFToken header.

  2. Retain the CSRF cookie from response’s csrftoken cookie.

  3. Now perform the primary POST /login/ request to login, including the CSRF token as a X-CSRFToken request header as well as the unchanged csrftoken cookie:

POST http://localhost:8000/login/

Raw request headers:
Host: localhost:8000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:37.0) Gecko/20100101 Firefox/37.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://localhost:8000/login/
Cookie: sessionid=5d1ccc96cbd7e7f290020aaedd64c1b3; csrftoken=KEMzraBRygy2ZJ7fLuvbfKhAEIPK9D4s; sso_login_url=
Connection: keep-alive
X-CSRFToken: KEMzraBRygy2ZJ7fLuvbfKhAEIPK9D4s

With for example payload as parameters:

&username=joe
&password=bloggs
&next=%2F

Note

Anti-CSRF protection for Self-service is managed via the XSRF-TOKEN cookie and not the csrftoken cookie which is received on each request.