AWS Tutorials, Spring Framework Tutorials

Thymeleaf OAuth2 Login with Spring Security and AWS Cognito

Last Updated: February 16, 2021 | Published: June 13, 2020

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:

<?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>

<?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">

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>2.3.0.RELEASE</version>

</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>

<java.version>11</java.version>

</properties>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-thymeleaf</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-security</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-oauth2-client</artifactId>

</dependency>

<groupId>org.thymeleaf.extras</groupId>

<artifactId>thymeleaf-extras-springsecurity5</artifactId>

</dependency>

</dependencies>

<build>

<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:

Thymeleaf application without authentication

… and if a user logs in:

Thymeleaf application with authentication

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:

AWS Cognito entry page

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:

Create a new AWS Cognito User pool

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:

Create app client AWS Cognito

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 App client settings OAuth2 AWS Cognito

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):

Configure AWS 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:

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

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:

@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("/");
  }
}

@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:

<!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>

<!DOCTYPE html>

<html lang="en"

xmlns:sec="http://www.thymeleaf.org/extras/spring-security"

xmlns:th="http://www.thymeleaf.org">

<head>

<title>OAuth2 Login AWS Cognito</title>

</head>

<body>

<div>

<! -- more to come -->

</a>

</div>

</form>

</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:

<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>

<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>

This section is only visible only for ROLE_USER.

</div>

This section is only visible only for ROLE_ADMIN.

</div>

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:

@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";
  }
}

@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:

<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>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-test</artifactId>

<groupId>org.junit.vintage</groupId>

<artifactId>junit-vintage-engine</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>org.springframework.security</groupId>

<artifactId>spring-security-test</artifactId>

</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:

@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"));
  }

}

@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:

@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"));
}

@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

Thymeleaf OAuth2 Login with Spring Security and AWS Cognito

Spring Boot setup with Thymeleaf and Spring Security

Required AWS Cognito set up in the AWS console

Configuring AWS Cognito as an identity provider

Secure Thymeleaf application with OAuth2 login

Testing the OAuth2 protection for Thymeleaf

Summary

Testing Spring Boot Applications Masterclass Testimonials

Become a More Productive and Confident Spring Boot Developer

Quicklinks

Recently Published