Securing your frontend application with a login and managing a user pool is something you can either write for yourself or use an external identity provider for. If you want to move fast with your prototype you usually pick the second option and search for an OpenID Connect (OIDC) and OAuth2 compliant identity provider. AWS offers its own solution for this: AWS Cognito. With this blog post, I'll guide you through every required step to configure AWS Cognito for your Spring Boot application using Spring Security to secure a Thymeleaf application with an OAuth2 login.
UPDATE: There is now the second part of this article available which covers the OIDC logout.
Spring Boot setup with Thymeleaf and Spring Security
The demo application uses Maven, Java 11, and Spring Boot 2.3.0. Besides the Spring Boot Starters for Web and Thymeleaf, we need the starters for Spring Security and OAuth2 Client:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | <?xml version="1.0" encoding="UTF-8"?> <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.3.0.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>de.rieckpil.blog</groupId> <artifactId>spring-security-aws-cognito-thymeleaf</artifactId> <version>0.0.1-SNAPSHOT</version> <name>spring-security-aws-cognito-thymeleaf</name> <description>Demo project using AWS Cognito with Spring Security</description> <properties> <java.version>11</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-oauth2-client</artifactId> </dependency> <dependency> <groupId>org.thymeleaf.extras</groupId> <artifactId>thymeleaf-extras-springsecurity5</artifactId> </dependency> <!-- Spring Boot Starter Test and Spring Security Test --> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project> |
The application exposes one view where users can log in using OAuth2 (OIDC to be more specific) and AWS Cognito to see messages based on their authentication:
… and if a user logs in:
Required AWS Cognito set up in the AWS console
Setting up AWS Cognito for this OAuth2 login with Spring Security requires some configuration steps in the AWS console.
First, log in to your AWS account and search for the AWS Cognito service:
Ensure you are in the correct AWS region you want to create the service for (I'm using eu-central-1). Next, click on Manage User Pools and create a new one:
You can give it any name you want. Continuing with Review defaults is enough for this user pool creation.
Once you created the user pools with the defaults, you can add app clients (left side menu: General Settings -> App Clients). Our Spring Boot application will act as a client. Therefore configure the client like the following:
The pre-selected configuration for the app client is fine. Just ensure you add the app client name. Once you created the client, store the client id and client secret somewhere e.g. as an environment variable (we need this later on for Spring Security).
As a next step, we configure the app client settings (left side menu: App Integration -> App Client Settings) as the following
It's important to add the correct callback URL. With Spring Security the path is /login/oauth2/code/{nameOfTheRegistration}. For local development, the localhost URL is all we need. You can add multiple (e.g your production URL) as a comma-separated list here. Ensure you select Authorization code grant and allow email and openid scope.
To use the sign-up and login-in page hosted by AWS Cognito, we have to configure a domain name for it (left side menu: App integration -> Domain Name):
As a final step, we can add the first user to our user pool. Go to General Settings -> Users and groups and add one.
To continue with the next section, ensure you have …
- the client id and client secret
- the AWS region you used
- your pool id (you can retrieve this inside General Settings)
… ready and at least one user inside your user pool.
Configuring AWS Cognito as an identity provider
Next comes the Spring Security configuration. Our Spring Boot application acts as an OAuth2 client and Spring Security provides a convenient way to configure this.
Open either your application.yml or application.properties file and add the following section:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | spring: security: oauth2: client: registration: cognito: clientId: ${COGNITO_CLIENT_ID} clientSecret: ${COGNITO_CLIENT_SECRET} scope: openid redirectUriTemplate: http://localhost:8080/login/oauth2/code/cognito clientName: spring-boot-backend provider: cognito: issuerUri: https://cognito-idp.{YOUR_REGION}.amazonaws.com/{YOUR_POOL_ID} userNameAttribute: cognito:username # or just username |
The configuration property spring.security.oauth2.client.registration contains a map of OAuth2 client registrations (there might be multiple for one application). In our example, we give the AWS Cognito registration the name cognito. Hence our callback URL is /login/oauth2/code/cognito.
Besides the configuration for scope, redirectUriTemplate, and clientName, we now need both the clientId and the clientSecret from the previous chapter. I'm using an environment variable to store both values and refer to them using ${NAME_OF_ENV_VARIABLE}.
Inside spring.security.oauth2.client.provider we now add information about the identity provider. The name of the provider has to match the name of the registration. As we are using OpenID Connect, we can add the OpenID Connect discovery endpoint to issuerUri. Make sure to construct the correct URI for your setup by replacing the region and your pool id.
With userNameAttribute we give Spring Security a hint which attribute to use for the username after calling the user info endpoint. Depending on your Cognito setup this is either cognito:username or username.
Next comes the actual security configuration for our application:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | @Configuration public class WebSecurityConfig extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http .csrf() .and() .authorizeRequests(authorize -> authorize.mvcMatchers("/").permitAll() .anyRequest().authenticated()) .oauth2Login() .and() .logout() .logoutSuccessUrl("/"); } } |
The configuration above ensures to allow access to our page "/" for everyone, enables CSRF, OAuth2 Login, and configures the application to redirect the user after he logs out to the entry page.
Secure Thymeleaf application with OAuth2 login
Now we are really close to having a working OAuth2 login with Thymeleaf and AWS Cognito using Spring Security.
Three things are missing:
- a login mechanism
- an ability to logout
- securing parts of the application only logged-in users
With the help of thymeleaf-extras-springsecurity5 we get the integration to Spring Security. This allows us to use well-known Spring Security expressions (think hasRole("XYZ") or isAuthenticated()) inside our template.
Let's take a look at the Thymeleaf template skeleton including the login and logout functionality:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | <!DOCTYPE html> <html lang="en" xmlns:sec="http://www.thymeleaf.org/extras/spring-security" xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="utf-8"> <meta content="width=device-width, initial-scale=1" name="viewport"> <title>OAuth2 Login AWS Cognito</title> <!-- CSS & JS for Bootstrap--> </head> <body> <div class="container"> <div> <! -- more to come --> <div sec:authorize="isAnonymous()"> <a class="btn btn-primary" th:href="@{/oauth2/authorization/cognito}" role="button"> Log in with Amazon Cognito </a> </div> <div sec:authorize="isAuthenticated()"> <form method="post" th:action="@{/logout}"> <input type="submit" class="btn btn-danger" value="Logout"/> </form> </div> </div> </div> </body> </html> |
Besides the standard Thymeleaf th namespace, we are including also the sec namespace. We'll use sec:authorize for our HTML elements to conditionally render them based on Spring Security expressions.
First, we need a way for users to log in to our application. Therefore we can add a link (HTTP GET) to /oauth2/authorization/cognito whenever an anonymous user enters the page. When clicking this link, Spring Security takes care of redirecting the user to AWS Cognito and fetching the access and ID token in the background (when the user enters correct credentials).
Next, we need the logout functionality for users. This should be only available if an authenticated user enters the page. For the logout part, we are using Spring Security's logout mechanism and make an HTTP POST to /logout.
Furthermore, let's add more examples for the Thymeleaf and Spring Security integration to conditionally render parts of the page:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | <div sec:authorize="isAuthenticated()"> <p>Hello, <strong th:text="${#authentication.name}"></strong>!</p> <p>Your authorities are: <strong th:each="authority : ${#authentication.authorities}"><span th:text="${authority.authority} + ' '"></span></strong></p> </div> <div sec:authorize="hasRole('USER')" class="alert alert-primary" role="alert"> This section is only visible only for ROLE_USER. </div> <div sec:authorize="hasRole('ADMIN')" class="alert alert-primary" role="alert"> This section is only visible only for ROLE_ADMIN. </div> <div sec:authorize="isAuthenticated()" class="alert alert-primary" role="alert"> This section is only visible only to authenticated users. </div> |
At the controller level, you can also request authentication information about the user and add different attributes to the Model e.g. based on a role:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | @Controller public class IndexController { @GetMapping public String getIndexPage(Model model, Authentication authentication) { if (authentication != null && authentication.isAuthenticated()) { if (authentication.getAuthorities().stream().anyMatch(a -> a.getAuthority().equals("ADMIN"))) { model.addAttribute("secretMessage", "Admin message is s3crEt"); } else { model.addAttribute("secretMessage", "Lorem ipsum dolor sit amet"); } } model.addAttribute("message", "AWS Cognito with Spring Security"); return "index"; } } |
Testing the OAuth2 protection for Thymeleaf
Most tutorials end here. Let's go a step further and take a look at how to test this application.
Besides the basic Spring Boot Starter Test, I'm including a dependency to effectively test Spring Boot applications in conjunction with Spring Security:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.springframework.security</groupId> <artifactId>spring-security-test</artifactId> <scope>test</scope> </dependency> |
With @WebMvcTest we can easily test our MVC controller in isolation. This allows us to write tests without having access to AWS and focus on testing our endpoint.
Using this annotation an auto-configured MockMvc instance is available and by default, our Spring Security configuration is also included.
A first test might verify an anonymous user can access the page (as our Spring Security config allows this) and the MVC model contains the message attribute:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | @WebMvcTest class IndexControllerTest { @Autowired private MockMvc mockMvc; @Test public void anonymousUsersShouldNotGetSecretMessage() throws Exception { this.mockMvc .perform(get("/") .with(anonymous())) .andExpect(status().isOk()) .andExpect(model().attributeDoesNotExist("secretMessage")) .andExpect(model().attribute("message", "AWS Cognito with Spring Security")); } } |
Further tests can ensure the result for different OIDC login scenarios (e.g. different claims or roles).
For this we can use the oidcLogin() method of the Spring Security test dependency and model different users:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | @Test public void authenticatedUsersShouldGetSecretMessage() throws Exception { this.mockMvc .perform(get("/") .with(oidcLogin())) .andExpect(status().isOk()) .andExpect(model().attributeExists("secretMessage", "message")) .andExpect(model().attribute("secretMessage", Matchers.stringContainsInOrder("Lorem ipsum"))); } @Test public void authenticatedAdminUsersShouldGetDetailedSecretMessage() throws Exception { this.mockMvc .perform(get("/") .with(oidcLogin().authorities(new SimpleGrantedAuthority("ROLE_ADMIN")))) .andExpect(status().isOk()) .andExpect(model().attributeExists("secretMessage", "message")) .andExpect(model().attribute("secretMessage", "Admin message is s3crEt")); } |
Summary
We are now at the end of this tutorial. Let's summarize the required steps to add an OAuth2 Login with AWS Cognito for a Thymeleaf application:
- create a user pool in the AWS console
- create and configure an OAuth2 client for the user pool
- configure the Spring Boot application to act as an OAuth2 client
- secure parts of the Thyemleaf application using the extras dependency for Spring Security
While this tutorial focussed solely on using AWS Cognito, the basic setup works with any OpenID Connect and OAuth2 compliant identity provider. If you use e.g. Keycloak you have to adjust the OAuth2 client registration and provider while the rest of the application works as expected.
UPDATE: There is now the second part of this article available which covers the OIDC logout.
You can find further Spring Boot and AWS related tutorials on my blog and the application for this guide on GitHub.
Have fun securing your Thymeleaf applications with OAuth2 login using AWS Cognito,
Phil
Hey,
Great articles, thanks.
I don’t know if it has to do with my cognito configuration, but my username attribute is “cognito:username” instead of just “username”.
after I change it in the configuration, I got it working.
Thanks again.
Hey Thiago,
thanks for the feedback and the hint. Not sure what’s different in your setup. I’ll double-check with a running example and update the article if required.
Kind regards,
Phil
I changed to:
usernameAttribute: username
and it worked.
thanks for the feedback. Depending on the OAuth2 configuration in Cognito it’s ether
usernameorcognito:username. I’ve updated the section.Hi Phil,
The username is the default attribute of cognito. Only custom attribute need to be prefixed with ‘custom:’. I tried your example with cognito:username it fails badly. The correct one is ‘username’ only and you have cognito as provider.
In your example you have demonstrated with localhost. With the same setup and having a url say example: https://www.mynameisgovind.net“. If you try to replace localhost:8080 with the new url and deploy it in aws, it does not work.
The domain is already registered, userpool authorization is updated to https://www.mynameisgovind.net/login/oauth2/code/cognito.
The AWS API Gateway routes to the index page. When you click on the ‘Log in with Amazon Cognito’ in the index page. The spring security login is displayed, you sign and cognito authenticates.
The cognito issues the authorization code but it does not route to the ‘https://www.mynameisgovind.net/’. This works good with localhost:8080 once authenticated you are routed back to localhost:8080.
Would be great if you could add in MVC to capture the oauth2 code and have it displayed.
thanks
Govind
Hey Govind,
thanks for your comment.
I currently have a Spring Boot application in production that uses the setup as described in the blog post. Replacing every localhost with the domain of the application worked for me.
However, I’m not using the AWS API Gateway for my setup and rather plain ECS with a Load Balancer to access the Spring MVC app.
Can you elaborate a little bit more about the AWS setup where the login with Cognito does not work?
Have a nice day,
Philip
Hi Philip,
We use containers (ecs) and aws api gateway to expose the end point or web server.
On the local machine the aws-elb routes to ‘localhost’ but when it is executed on aws, the elb does not route it to the actual domain https://www.mynameisgovind.net/
Getting 302 error – redirect issue. The elb is not routing it to the https://www.mynameisgovind.net/ where as for localhost:8080 but default its redirecting.
regards
govind
I’ve not much experience with the API Gateway of AWS but I assume there must be some access logs available to debug and trace what is happening behind the scenes?
Can you try to open the network tab when you click the login with Cognito button to see the full URL that also contains the redirect URL?
My application is also running within ECS and once you run with more than one instance I had to configure sticky sessions for the ELB.
we did trouble shoot with AWS engineer, the redirect is happening to elb (elastic load balancer) which then times out. The trace indicates the authentication is successful. After the authentication the “spring mvc” is not redirecting properly to the index.html page.
oh okay. Then I guess the next step would be to create an issue on the Spring Web MVC or Spring Security repository, as I might not be of any further help.
When you logout and then select Log In With Amazon Cognito you are no longer prompted for credentials and instead just taken to the authenticated page. Would have assumed that logout would result in being asked for credentials to re-authenticate ?
Thanks
Hi Graeme,
that’s true. The reason for this is that the page from AWS Cognito where you log in also has a remember me the functionality. Whenever you now re-enter this login dialog, you are automatically signed in. I assume this can be configured on the AWS side.
How do you properly setup Groups , I cannot seem to get the admin message to display.
Hi Adam,
I’ve not done this before with AWS Cognito. Maybe this link can help: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html
Have a nice day,
Philip
[…] one of the previous blog posts, we configured a Thymeleaf Spring Boot application for an OAuth 2 Login with Spring Security and […]
Hi,
I am facing issue in redirect.
Error : [invalid_token_response] An error occurred while attempting to retrieve the OAuth 2.0 Access Token Response: I/O error on POST request for “https://roarapps.auth.ap-south-1.amazoncognito.com/oauth2/token”: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target; nested exception is javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.
Any Solution?
Hi Anmol,
that looks like an SSL error from the JRE. Did you customize your keystore/truststore by any chance?
Kind regards,
Philip
Hi Philip,
I have created a self signed certificate using java keytool and using it in project.
is there any solution possible for this?
Hi Anmol,
Maybe this question on Stack Overflow can help.
Otherwise (and if you don’t need the self-signed certificate), try installing a fresh JDK on your machine.
Kind regards,
Philip
One more doubt philip,
if i use redirect uri as http://localhost:8081/roar/cognitoLogin where /cognitoLogin is a servlet then after cognito login first it redirects to ‘http://localhost:8081/roar/cognitoLogin ‘ but automatically it redirects to https://localhost:8081/roar/login/oauth2/code/cognito to this.
i am not able to resolve this issue.
Can you share a reproducible example over a GitHub repository? Without seeing your entire setup and the exact configuration, it’s quite hard to help here.
Hello, in case anyone interested.
Here is an example of integrating Cognito with Groups into a spring boot v3 project.
https://github.com/sshareit/cognito-oauth2
Thanks for sharing, David!