Where to save a JWT in a browser-based application and how to use it

zero_coding picture zero_coding · Oct 13, 2014 · Viewed 44.9k times · Source

I'm trying to implement JWT in my authentication system and I have a few questions. To store the token, I could use cookies but it's also possible to use localStorage or sessionStorage.

Which would be the best choice?

I have read that JWT protects the site from CSRF. However, I can't imagine how that would work assuming I save the JWT token in cookie storage.

How would it then protect from CSRF?

Update 1
I saw some usage samples like the following:

curl -v -X POST -H "Authorization: Basic VE01enNFem9FZG9NRERjVEJjbXRBcWJGdTBFYTpYUU9URExINlBBOHJvUHJfSktrTHhUSTNseGNh"

How can I implement that when I make a request to server from the browser? I also saw that some implement the token in the URL:

http://exmple.com?jwt=token

If I would make a request via AJAX then I could set an header like jwt: [token] and then I could read the token from header.

Update 2

I installed the Advanced REST Client Google Chrome extension and was able to pass the token as a custom header. Is it possible to set this header data via Javascript when making a GET request to the server?

Answer

João Angelo picture João Angelo · Nov 2, 2016

Choosing the storage is more about trade-offs than trying to find a definitive best choice. Let's go through a few options:

Option 1 - Web Storage (localStorage or sessionStorage)

Pros

  • The browser will not automatically include anything from Web storage into HTTP requests making it not vulnerable to CSRF
  • Can only be accessed by Javascript running in the exact same domain that created the data
  • Allows to use the most semantically correct approach to pass token authentication credentials in HTTP (the Authorization header with a Bearer scheme)
  • It's very easy to cherry pick the requests that should contain authentication

Cons

  • Cannot be accessed by Javascript running in a sub-domain of the one that created the data (a value written by example.com cannot be read by sub.example.com)
  • ⚠️ Is vulnerable to XSS
  • In order to perform authenticated requests you can only use browser/library API's that allow for you to customize the request (pass the token in the Authorization header)

Usage

You leverage the browser localStorage or sessionStorage API to store and then retrieve the token when performing requests.

localStorage.setItem('token', 'asY-x34SfYPk'); // write
console.log(localStorage.getItem('token')); // read

Option 2 - HTTP-only cookie

Pros

  • It's not vulnerable to XSS
  • The browser automatically includes the token in any request that meets the cookie specification (domain, path and lifetime)
  • The cookie can be created at a top-level domain and used in requests performed by sub-domains

Cons

  • ⚠️ It's vulnerable to CSRF
  • You need to be aware and always consider the possible usage of the cookies in sub-domains
  • Cherry picking the requests that should include the cookie is doable but messier
  • You may (still) hit some issues with small differences in how browsers deal with cookies
  • ⚠️ If you're not careful you may implement a CSRF mitigation strategy that is vulnerable to XSS
  • The server-side needs to validate a cookie for authentication instead of the more appropriate Authorization header

Usage

You don't need to do anything client-side as the browser will automatically take care of things for you.

Option 3 - Javascript accessible cookie ignored by server-side

Pros

  • It's not vulnerable to CSRF (because it's ignored by the server)
  • The cookie can be created at a top-level domain and used in requests performed by sub-domains
  • Allows to use the most semantically correct approach to pass token authentication credentials in HTTP (the Authorization header with a Bearer scheme)
  • It's somewhat easy to cherry pick the requests that should contain authentication

Cons

  • ⚠️ It's vulnerable to XSS
  • If you're not careful with the path where you set the cookie then the cookie is included automatically by the browser in requests which will add unnecessary overhead
  • In order to perform authenticated requests you can only use browser/library API's that allow for you to customize the request (pass the token in the Authorization header)

Usage

You leverage the browser document.cookie API to store and then retrieve the token when performing requests. This API is not as fine-grained as the Web storage (you get all the cookies) so you need extra work to parse the information you need.

document.cookie = "token=asY-x34SfYPk"; // write
console.log(document.cookie); // read

Additional Notes

This may seem a weird option, but it does has the nice benefit that you can have storage available to a top-level domain and all sub-domains which is something Web storage won't give you. However, it's more complex to implement.


Conclusion - Final Notes

My recommendation for most common scenarios would be to go with Option 1, mostly because:

  • If you create a Web application you need to deal with XSS; always, independently of where you store your tokens
  • If you don't use cookie-based authentication CSRF should not even pop up on your radar so it's one less thing to worry about

Also note that the cookie based options are also quite different, for Option 3 cookies are used purely as a storage mechanism so it's almost as if it was an implementation detail of the client-side. However, Option 2 means a more traditional way of dealing with authentication; for a further read on this cookies vs token thing you may find this article interesting: Cookies vs Tokens: The Definitive Guide.

Finally, none of the options mention it, but use of HTTPS is mandatory of course, which would mean cookies should be created appropriately to take that in consideration.