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:

* `Cross-site request forgery <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_
* `Cross-Site Request Forgery (CSRF) <https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29>`_

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


.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM