REST Security with JWT using Java and Spring Security

Security

Security is the enemy of convenience, and vice versa. This statement is true for any system, virtual or real, from the physical house entrance to web banking platforms. Engineers are constantly trying to find the right balance for the given use case, leaning to one side or the other. Usually, when a new threat appears, we move towards security and away from convenience. Then, we see if we can recover some lost convenience without reducing the security too much. Moreover, this vicious circle goes on forever.

Let’s try to see where REST services currently stand regarding security and convenience. REST (which stands for Representational State Transfer) services started off as an extremely simplified approach to Web Services that had huge specifications and cumbersome formats, such as WSDL for describing the service, or SOAP for specifying the message format. In REST, we have none of those. We can describe the REST service in a plain text file and use any message format we want, such as JSON, XML or even plain text again. The simplified approach was applied to the security of REST services as well; no defined standard imposes a particular way to authenticate users.

Although REST services do not have much specified, an important one is the lack of state. It means the server does not keep any client state, with sessions as a good example. Thus, the server replies to each request as if it was the first the client has made. However, even now, many implementations still use cookie based authentication, which is inherited from standard website architectural design. The stateless approach of REST makes session cookies inappropriate from the security standpoint, but nevertheless, they are still widely used. Besides ignoring the required statelessness, simplified approach came as an expected security trade-off. Compared to the WS-Security standard used for Web Services, it is much easier to create and consume REST services, hence convenience went through the roof. The trade-off is pretty slim security; session hijacking and cross-site request forgery (XSRF) are the most common security issues.

In trying to get rid of client sessions from the server, some other methods have been used occasionally, such as Basic or Digest HTTP authentication. Both use an Authorization header to transmit user credentials, with some encoding (HTTP Basic) or encryption (HTTP Digest) added. Of course, they carried the same flaws found in websites: HTTP Basic had to be used over HTTPS since username and password are sent in easily reversible base64 encoding, and HTTP Digest forced the use of obsolete MD5 hashing that is proven to be insecure.

Finally, some implementations used arbitrary tokens to authenticate clients. This option seems to be the best we have, for now. If implemented properly, it fixes all the security problems of HTTP Basic, HTTP Digest or session cookies, it is simple to use, and it follows the stateless pattern.

However, with such arbitrary tokens, there’s little standard involved. Every service provider had his or her idea of what to put in the token, and how to encode or encrypt it. Consuming services from different providers required additional setup time, just to adapt to the specific token format used. The other methods, on the other hand (session cookie, HTTP Basic and HTTP Digest) are well known to developers, and almost all browsers on all devices work with them out of the box. Frameworks and languages are ready for these methods, having built-in functions to deal with each seamlessly.

JWT

JWT (shortened from JSON Web Token) is the missing standardization for using tokens to authenticate on the web in general, not only for REST services. Currently, it is in draft status as RFC 7519. It is robust and can carry a lot of information, but is still simple to use even though its size is relatively small. Like any other token, JWT can be used to pass the identity of authenticated users between an identity provider and a service provider (which are not necessarily the same systems). It can also carry all the user’s claim, such as authorization data, so the service provider does not need to go into the database or external systems to verify user roles and permissions for each request; that data is extracted from the token.

Here is how JWT is designed to work:

Clients logs in by sending their credentials to the identity provider.

The identity provider verifies the credentials; if all is OK, it retrieves the user data, generates a JWT containing user details and permissions that will be used to access the services, and it also sets the expiration on the JWT (which might be unlimited).

Identity provider signs, and if needed, encrypts the JWT and sends it to the client as a response to the initial request with credentials.

Client stores the JWT for a limited or unlimited amount of time, depending on the expiration set by the identity provider.

Client sends the stored JWT in an Authorization header for every request to the service provider.

For each request, the service provider takes the JWT from the Authorization header and decrypts it, if needed, validates the signature, and if everything is OK, extracts the user data and permissions. Based on this data solely, and again without looking up further details in the database or contacting the identity provider, it can accept or deny the client request. The only requirement is that the identity and service providers have an agreement on encryption so that service can verify the signature or even decrypt which identity was encrypted.

This flow allows for great flexibility while still keeping things secure and easy to develop. By using this approach, it is easy to add new server nodes to the service provider cluster, initializing them with only the ability to verify the signature and decrypt the tokens by providing them a shared secret key. No session replication, database synchronization or inter-node communication is required. REST in its full glory.

The main difference between JWT and other arbitrary tokens is the standardization of the token’s content. Another recommended approach is to send the JWT token in the Authorization header using the Bearer scheme. The content of the header should look like this:

Authorization: Bearer <token>

Implementation

For REST services to work as expected, we need a slightly different authorization approach compared to classic, multi-page websites.

Instead of triggering the authentication process by redirecting to a login page when a client requests a secured resource, the REST server authenticates all requests using the data available in the request itself, the JWT token in this case. If such an authentication fails, redirection makes no sense. The REST API simply sends an HTTP code 401 (Unauthorized) response and clients should know what to do; for example, a browser will show a dynamic div to allow the user to supply the username and password.

On the other hand, after a successful authentication in classic, multi-page websites, the user is redirected by using HTTP code 301 (Moved permanently), usually to a home page or, even better, to the page the user initially requested that triggered the authentication process. With REST, again this makes no sense. Instead we would simply continue with the execution of the request as if the resource was not secured at all, return HTTP code 200 (OK) and expected response body.

Spring Security

Now, let’s see how can we implement the JWT token based REST API using Java and Spring, while trying to reuse the Spring security default behavior where we can. As expected, Spring Security framework comes with many ready to plug-in classes that deal with “old” authorization mechanisms: session cookies, HTTP Basic, and HTTP Digest. However, it lacks the native support for JWT, and we need to get our hands dirty to make it work.

First, we start with the usual Spring Security filter definition in web.xml:

Note that the name of the filter must be exactly springSecurityFilterChain for the rest of the Spring config to work out of the box.

Next comes the XML declaration of the Spring beans related to security. In order to simplify the XML, we will set the default namespace to security by adding xmlns="http://www.springframework.org/schema/security" to the root XML element. The rest of the XML looks like this:

(1) In this line, we activate @PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize annotations on any spring beans in the context.

(2) We define the login and signup endpoints to skip security; even “anonymous” should be able to do these two operations.

(3) Next, we define the filter chain applied to all requests while adding two important configs: Entry point reference and setting the session creation to stateless (we do not want the session created for security purposes as we are using tokens for each request).

(4) We do not need csrf protection because our tokens are immune to it.

(5) Next, we plug in our special authentication filter within the Spring’s predefined filter chain, just before the form login filter.

(6) This bean is the declaration of our authentification filter; since it is extending Spring’s AbstractAuthenticationProcessingFilter, we need to declare it in XML to wire its properties (auto wire does not work here). We will explain later what the filter does.

(7) The default success handler of AbstractAuthenticationProcessingFilter is not good enough for REST purposes because it redirects the user to a success page; that is why we set our own here.

(8) The declaration of the provider created by the authenticationManager is used by our filter to authenticate users.

Now let’s see how we implement the specific classes declared in the XML above. Note that Spring will wire them for us. We start with the simplest ones.

RestAuthenticationEntryPoint.java

public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {
@Override
public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException {
// This is invoked when user tries to access a secured REST resource without supplying any credentials
// We should just send a 401 Unauthorized response because there is no 'login page' to redirect to
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized");
}
}

JwtAuthenticationSuccessHandler.java

public class JwtAuthenticationSuccessHandler implements AuthenticationSuccessHandler {
@Override
public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) {
// We do not need to do anything extra on REST authentication success, because there is no page to redirect to
}
}

This simple override removes the default behavior of a successful authentication (redirecting to home or any other page the user requested). If you are wondering why we do not need to override the AuthenticationFailureHandler, it is because default implementation will not redirect anywhere if its redirect URL is not set, so we just avoid setting the URL, which is good enough.

This class is the entry point of our JWT authentication process; the filter extracts the JWT token from the request headers and delegates authentication to the injected AuthenticationManager. If the token is not found, an exception is thrown that stops the request from processing. We also need an override for successful authentication because the default Spring flow would stop the filter chain and proceed with a redirect. Keep in mind we need the chain to execute fully, including generating the response, as explained above.

In this class, we are using Spring’s default AuthenticationManager, but we inject it with our own AuthenticationProvider that does the actual authentication process. To implement this, we extend the AbstractUserDetailsAuthenticationProvider, which requires us only to return UserDetails based on the authentication request, in our case, the JWT token wrapped in the JwtAuthenticationToken class. If the token is not valid, we throw an exception. However, if it is valid and decryption by JwtUtil is successful, we extract the user details (we will see exactly how in the JwtUtil class), without accessing the database at all. All the information about the user, including his or her roles, is contained in the token itself.

Finally, JwtUtil class is in charge of parsing the token into User object and generating the token from the User object. It is straightforward since it uses the jjwt library to do all the JWT work. In our example, we simply store the username, user ID and user roles in the token. We could also store more arbitrary stuff and add more security features, such as the token’s expiration. Parsing of the token is used in the AuthenticationProvider as shown above. The generateToken() method is called from login and signup REST services, which are unsecured and will not trigger any security checks or require a token to be present in the request. In the end, it generates the token that will be returned to the clients, based on the user.

Conclusion

Although the old, standardized security approaches (session cookie, HTTP Basic, and HTTP Digest) will work with REST services as well, they all have problems that would be nice to avoid by using a better standard. JWT arrives just in time to save the day, and most importantly it is very close to becoming an IETF standard.

JWT’s main strength is handling user authentication in a stateless, and therefore scalable, way, while keeping everything secure with up-to-date cryptography standards. Storing claims (user roles and permissions) in the token itself creates huge benefits in distributed system architectures where the server that issues the request has no access to the authentication data source.

About the author

Dejan has many years of experience working with top Java and JavaScript frameworks. He is proficient in Spring/JEE, HTML, CSS, and several popular JavaScript libraries, not to mention a complimentary fluency in the DB layer. Dejan is a powerful addition to any team due to his competency with version control systems (SVN/Git) and internal development tools (Ant/Maven), as well as his results-driven and flexible mindset. [click to continue...]

Comments

Bradley Suira

Great post, i have a question for you, in your experience what do you do when in the server side you need reports or download such a pdf file or excel (for export options in documents), i found approaches like using an iframe and pass the token through an input hidden via http post but i think that isn't de best way, the other way is using the current token, make an request to get other token (only for downloads) and then call some url like domain.test/url/download?token=xxxx, but again i think that isn't the best way.
Regards

Saket Puranik

Hi,
Nice post. Just a question , where are you setting your Authorization Bearer header. We are making a form submit on login so this is a doubt from my side.
Regards
Saket

Selasie Hanson

Great blog post. Is there a link to the full source code?

Gaurav Garg

JwtAuthenticationToken, JwtTokenMalformedException, AuthenticatedUser, JwtTokenMissingException and User...these five classes are missing. Please help me to find these classes.
Thanks in advance

Gaurav Garg

JwtAuthenticationToken cannot be a type of UsernamePasswordAuthenticationToken.

Jorge Morando

i don't know what to say, it is a nice (beginning of a) post, the sources (imports) are missing, i think you should never neglect them, they are quite important to the unfamiliarized reader. JWT also involves client side manipulation of the token, so you should also include a simple dummy example to complete this tut.
other than that, nice start.

Matheus Eduardo Machado Moreir

I'm interested in the full source code too.

James richard

Great article DEJAN . Simple and very useful description. I think you should provide little more code. Awesome stuff.

Narwen Tamang

Can i have the source code in github?

Stephan Zerhusen

Hi everybody! I've written a small demo that is partially based on this blog entry. Perhaps it is interesting for you: https://github.com/szerhusenBC/jwt-spring-security-demo

Rajesh

Hi Bro,
Thanks a lot. Your code works smoothly. I have some doubts bro.

Rajesh

Bro try at https://github.com/szerhusenBC/jwt-spring-security-demo. It is working smoothly

Stephan Zerhusen

What kind of doubts are these?

Stephan Zerhusen

Hi, you can take a look at my demo. It's based on this blog entry: https://github.com/szerhusenBC/jwt-spring-security-demo

I feel the above source code doesn't work. FIrst of all, JwtAutoehtnicationToken should inhehir UsernamePasswordToken or AUthentication

Benson

This blog's source code cannot apple to apple.

Benson

agree

Benson

yes, so that's why I think the above source doesn't work.

Benson

yes, totally this blog is totally useless.

Benson

such a garbage blog!!!!! no source code.....

Benson

I am wondering the above proposed source code works...

Andrew Glassman

I usually determine if my code runs by feeling as well. I do find that spelling classes, and keywords correctly tends to help.

Thomas Abraham

Hey Stephan,
Thanks a lot for the implementation.
But a small query. How can we invalidate the token when the user clicks on logout. Actually you are only removing it from the browser local cache. which is not really invalidating the token in the server. Any suggestions for doing that?

blakeb

Great post!
I have message to other guys from comments: Copy-paste developers are not so cool ;)

Stephan Zerhusen

Hmmm, the idea behind my demo is, that there is as less state information as possible on the server. In the demo the server doesn't know about any logged in clients. The only thing you can do is to validate if the token is expired. Perhaps you have to store invalidated token hashes on the server so that it can't be used again in the future? Do anybody have another idea?

Stephan Zerhusen

Thank you!

Thomas Abraham

If we are storing all invalidated tokens then it could heavily accumulated. and storing it in a db means a for every request a db call has to be made for validation. Which is very expensive and process intensive.
Does anyone have any idea what is the best way to achieve this?

Stephan Zerhusen

I googled a bit and the most solutions I found are basing on a blacklist approach similar to what I mentioned before. Here are some interesting tips: http://stackoverflow.com/questions/21978658/invalidating-json-web-tokens#23089839

Pavel Belenkovich

One important problem: In JwtAuthenticationFilter.successfulAuthentication() must remove super.successfulAuthentication() call. This causes a redirection after the processing of the request, and the following error in the browser (using angular2-jwt): "XMLHttpRequest cannot load .. The request was redirected to .. which is disallowed for cross-origin requests that require preflight."

Saurab Raj Shrestha

Toptal blogs are totally useless. Guys don't write just to appear in order to get hired.

Andrea Grassi

For all those who wonder how would it be to have the complete project, someone on gitlab recreated it perfectly.
https://gitlab.com/palmapps/jwt-spring-security-demo/ ;)
Enjoy it!

Sanjay Patel

Hi Stephan, great demo! A couple of questions: (1) Seems that you aren't prefixing the token with "Bearer" in the Authorization header. Should we prefix it or not - what would be the best practice? (2) Extending JwtAuthenticationTokenFilter from UsernamePasswordAuthenticationFilter is clever, but I see that Spring's RememberMeAuthenticationFilter extends GenericFilterBean instead, and uses its own RememberMeAuthenticationToken instead of a UsernamePasswordAuthenticationToken as used by you. I'd love to go your way because it's a lot less work, but just wanted to confirm if you see any downside, and would instead recommend the RememberMe kind of implementation for production? (Another interesting approach that comes to my mind is whether we can customize remember-me to produce JWT tokens and use Authorization header instead of a cookie.)

Stephan Zerhusen

Hi Sanjay!
To (1): This demo is just a technical case study und I don't use it in a production environment yet. I don't know what best practice is. Maybe you can find out any information related to the prefix and share the information?
To (2): Your idea extending the GenericFilterBean is great. It makes the security configuration easier! I changed that under https://github.com/szerhusenBC/jwt-spring-security-demo/issues/7 . Perhaps you can review that?

Sanjay Patel

Hello Stephen, thanks for the quick and great response! I pulled your changes. Looks good to my eyes. Seems to be working well.
Meanwhile, I came across Spring's AbstractPreAuthenticatedProcessingFilter ( See https://spring.io/guides/tutorials/spring-security-and-angular-js/#_token_authentication ) and was wondering whether extending that would be more ideal. Any idea? Spring seems to be having many filters such as RequestHeaderAuthenticationFilter extending from that.

Stephan Zerhusen

I looked into the AbstractPreAuthenticatedProcessingFilter and there is nothing, that is helpfull for JWT mechanic. To be worse in this class a session is managed and we don't have and don't want to have a session. The server should stay stateless. Following the KISS principle I think extending GenericFilterBean is the better way!

Sanjay Patel

Makes quite sense, thanks!
Another thing that strikes my mind is whether, instead of using the UsernamePasswordAuthenticationToken, we should ideally use a custom JwtAuthenticationToken.

John

Thanks Stephan!
Could you please help me with the database settings, where in the code is the connection created...?

Stephan Zerhusen

Hi, John! In my demo the H2 database is used and automatically configured by Spring Boot. If you want to connect to another DB, you have to specify the settings in the application.yml. Here is an example for a MySQL db:
spring:
jpa:
hibernate:
# possible values: validate | update | create | create-drop
ddl-auto: create-drop
datasource:
url: jdbc:mysql://localhost/myDB
username: myUser
password: myPassword
driver-class-name: com.mysql.jdbc.Driver
You can find the reference for the possible property keys under http://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html

John

Great, it's working now. Many Thanks!

Aman Gupta

Nice blog, really helpful but need to put little extra effort to get it working...

Gustavo Salgado

Hello, this great explanation, thank you very much for sharing this information; I have a question regarding CSRF, why tokes are immune to it ?. Thank you

Sergi and Replace

Great example. What do you think on the approach of adding the expiration date in the jwt token in order to no having eternal tokens?

Richard Seldon

Here are 4 samples that use plain Java / plain Java Spring / Spring Security for MVC / Spring Security for APIs.
Please see the README for each repo to get the libraries that each uses too.
https://github.com/auth0-samples/auth0-servlet-sample
https://github.com/auth0-samples/auth0-spring-mvc-sample
https://github.com/auth0-samples/auth0-spring-security-mvc-sample
https://github.com/auth0-samples/auth0-spring-security-api-sample
And if interested in Single Sign On too with JWT security:
https://github.com/auth0-samples/auth0-spring-security-mvc-sso-sample
Disclaimer, I work for Auth0, and wrote the above samples and libraries.

Taesu Kim

Very nice article. Explains JWT technology from A to Z.
As a person who only used the traditional session/cookie based tech, I have a few question to ask:
1. Is there a way to invalidate the token if it is from a different device?
2. How am I supposed to know whether the token provided is a stolen one? I can easily copy and paste the entire token and provide it.
Thank you!

Aaron D.

This post completely wasted many hours for me. In the end, I was able to use vanilla Spring (with Oauth2 and JWT) to authenticate via JWT token with only needing to write a custom UserAuthenticationConverter to have the authentication principal be a custom user which includes the custom claims contained in the JWT. Not using the custom claims was even easier. The example above is simply not good, do not follow it. (I now question Toptal's competence after this.)
This post should be either completely reworked or removed.

Darwin

On the client side, is it possible to store a JWT as a secure, HTTP-only cookie <b>and</b> present it as a bearer token <b>without</b> using Angular.JS?

André Felipe C Leite

https://gitlab.com/palmapps/jwt-spring-security-demo/tree/master
Here you get the pom file and found the missing classes.
I hope this help you.

Wade Dorrell

I was just going to say, a good bit of that code appears to be lifted from this article (comments and such intact.) But it is more complete!

kiriti komaragiri

JwtAuthenticationToken class is missing...I have included 0.7.0 and also tried with 0.5.0 version of jjwt but still no luck

__ldh

No way bro.

__ldh

I'm interested in the answer to this as well. To take a stab at it, my understanding is that in a CSRF attack a malicious actor (website, email, etc. with an HTML Form which POSTs to your API) normally relies on the fact that your browser already contains a valid session cookie for the site it's trying to forge a request to, and the browser dutifully fulfills what it thinks is your request by automatically including that cookie to the domain it belongs to when it issues the request. Your API sees a valid cookie and performs the action.
In the JWT scenario, your User Agent (e.g. JavaScript in the browser) is responsible for sending the token in an HTTP header, the browser doesn't know to do it automatically. Malicious code from a different source has no way to get that token from your client.

Pavan kumar

can any one provide me source code with xml comfigurations

Aneesh David

Hi , Jwt is doing wee for my rest webservice application.i would like to call the webservice from ios app(swift3) . i am facing jwt token verification failure on webservice. Could you please help me?

slowdrive

I believe this is handled by CORS, which only accept requests from hosts that you allow, and reject everything else

Mohamed Malhar

Thank you very much for the article. Exactly what I was looking for.

Mohamed Malhar

Thank you Stephan for for sharing the demo.

Stephan Zerhusen

You're welcome ;)

Farrukh Pervaiz

I got everything right but can't seem to understand what to do with this line
return new AuthenticatedUser(parsedUser.getId(), parsedUser.getUsername(), token, authorityList);
where do I create AuthenticatedUser, do I need to implement my own class for this and if so, how?

TS

How does using JWT prevent against session hijacking? If an attacker has the JWT the attacker can do whatever the victim user has authorized access to do.

Leo Arreguin Jr

SSL is required for sure to prevent token leakage and session hijacking.

bo

Great Post!! Thanks for the detailed explanation. I'm not able to understand what is difference between identity provided and service provider in JWT architecture you explained?

devadventurer

Since there is no session context between requests, there is no need to prove that another request sent by the same client belongs to the same client. In this scenario the REST API is stateless. The only thing that must be protected here is the token itself.

devadventurer

I think this post is a great way to better understand some parts of Spring Security. But I think that using OAuth2 and JWT may be a better approach. Just by using client_credentials grant type could help here with less effort.

Lalchand Mali

Hello,
I am using jwt token for authorization, but i came across a problem with jwt . If we are sending multiple async request using same jwt token then only one request will be processed other will be rejected.
how can i solve this problem? so i can serve multiple async request.

Eralp Bayraktar

This is Java practice.. look at Java codes from all over the internet. 90% of them are importless. Java community needs to come to 2017, so many anti patterns.

Eralp Bayraktar

Amazing how Java developers think this is a "small" demo with 75 files, I couldn't even count because of all the directories. Thank god there is spring or it would be 200+ configuration files as well.

Eralp Bayraktar

Where is JwtAuthenticationToken??????????

Teo

+2

Mathieu Bourgeois

Hello, thanks for this tutorial !
I just have a problem with POST request : It's like if they were not catch at all, but the GET request are well catched and checked. Am I the onlly one to have that ?

Ahmet CETINKAYA

How can we hash password in db

Harshavardhan Musanalli

Use https://docs.spring.io/spring-security/site/docs/current/apidocs/org/springframework/security/crypto/bcrypt/BCryptPasswordEncoder.html to hash the password

Rodolfo Rojas

Hey Dejan,
First of all, great thanks for this excellent post, it was very helpful to me. Right now I am struggling with my implementation that in fact is very similar as you implement, basically the filer is being called twice, I check the logs and the authentication was success in the both fist and second call, at this time I'm stuck with this, I hope you can give me some clues about what is going on.

Amit Jain

Hi Stephan, I reference your demo code - did some changes to it as per our need. I am getting error "java.lang.IllegalStateException: Cannot create a session after the response has been committed". Also posted question on stackoverflow https://stackoverflow.com/questions/44897050/spring-java-lang-illegalstateexceptioncannot-create-a-session-after-the-respons. Any suggestion on it?

Stephan Zerhusen

Hi Amit, my demo application is sessionless.In "WebSecurityConfig" there is the line ".sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)". So maybe you're trying to create a session while using SessionCreationPolicy.STATELESS?

Nyimax

i also faced the same problem. JwtAuthenticationToken missing in that jar

Dejan has many years of experience working with top Java and JavaScript frameworks. He is proficient in Spring/JEE, HTML, CSS, and several popular JavaScript libraries, not to mention a complimentary fluency in the DB layer. Dejan is a powerful addition to any team due to his competency with version control systems (SVN/Git) and internal development tools (Ant/Maven), as well as his results-driven and flexible mindset.