Security Top

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:


1. Introduction

Integration testing is crucial when validating that an application is working properly. Also, we should correctly test authentication as it's a sensitive part. Testcontainers allow us to launch Docker containers during the testing phase to run our tests against actual technical stacks.

In this article, we'll see how to set up integration tests against an actual Keycloak instance using Testcontainers.

2. Setting up Spring Security with Keycloak

We'll need to set up Spring Security, Keycloak configuration, and finally Testcontainers.

2.1. Setting up Spring Boot and Spring Security

Let's start by setting up security, thanks to Spring Security. We'll need the spring-boot-starter-security dependency. Let's add it to our pom:


We'll use the spring-boot parent pom. Hence we don't need to specify the version of the libraries specified in its dependencies management.

Next, let's create a simple controller to return a User:

public class UserController {

    public UserDto getMe() {
        return new UserDto(1L, "janedoe", "Doe", "Jane", "[email protected]");

At this point, we have a secure controller that responds to requests on “/users/me”. When launching the application, Spring Security generates a password for the user ‘user', visible in the application logs.

2.2. Configuring Keycloak

The easiest way to launch a local Keycloak is to use Docker. Let's run a Keycloak container with an admin account already configured:

docker run -p 8081:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin start-dev

Let's open a browser to the URL http://localhost:8081 to access the Keycloak console:

Next, let's create our realm. We'll call it baeldung:

We need to add a client, which we'll name baeldung-api:

Finally, let's add a Jane Doe user using the Users menu:

Now that we've created our user, we must assign it a password. Let's choose s3cr3t and uncheck the temporary button:

We've now set up our Keycloak realm with a baeldung-api client and a Jane Doe user.

We'll next configure Spring to use Keycloak as the identity provider.

2.3. Putting Both Together

First, we'll delegate the identification control to a Keycloak server. For this, we'll use a convenient starter, keycloak-spring-boot-starter. Hence, let's add it to our pom:


We'll also need the keycloak-adapter-bom dependency. Specifically, it adds the main adapter to fully use Spring autoconfiguration, as well as the libraries required to connect Keycloak and different web containers, including Tomcat:


Then, let's create a configuration class that uses Spring properties to configure the Keycloak adapter.

public class KeycloakConfiguration {

    public KeycloakSpringBootConfigResolver keycloakConfigResolver() {
        return new KeycloakSpringBootConfigResolver();

Let's continue by configuring Spring Security to use the Keycloak configuration:

@ConditionalOnProperty(name = "keycloak.enabled", havingValue = "true", matchIfMissing = true)
public class KeycloakSecurityConfiguration extends KeycloakWebSecurityConfigurerAdapter {

    public void configureGlobal(AuthenticationManagerBuilder auth) {

    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new NullAuthenticatedSessionStrategy();

    protected void configure(HttpSecurity http) throws Exception {


We're building a stateless application with bearer-only authentication. For this reason, we'll use the NullAuthenticatedSessionStrategy as a session strategy. Moreover, @ConditionalOnProperty allows us to disable the Keycloak configuration by setting the keycloak.enable property to false.

Finally, let's add the configuration needed to connect to our Keycloak in our file:


Our application is now secure and queries Keycloak on each request to validate the authentication.

3. Setting up Testcontainers for Keycloak

3.1. Exporting the Realm Configuration

The Keycloak container starts without any configuration in place. Thus, we must import it when the container starts as a JSON file. Let's export this file from our currently running instance:

Unfortunately, Keycloak does not export users. In this case, we must manually edit the resulting realm-export.json file and add our Jane Doe to it. Let's add this configuration just before the final curly brace:

"users": [
    "username": "janedoe",
    "email": "j[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "enabled": true,
    "credentials": [
        "type": "password",
        "value": "s3cr3t"
    "clientRoles": {
      "account": [

Let's include our realm-export.json file to our project in an src/test/resources/keycloak folder. We'll use it during the launch of our Keycloak container.

3.2. Setting up Testcontainers

Let's add the testcontainers dependency as well as testcontainers-keycloak, which allows us to launch a Keycloak container:


Next, let's create a class from which all our tests will derive. We use it to configure the Keycloak container, launched by Testcontainers:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public abstract class KeycloakTestContainers {

    static final KeycloakContainer keycloak = new KeycloakContainer().withRealmImportFile("keycloak/realm-export.json");

Declaring our container statically will ensure it will be instantiated once for all of our tests. We're specifying the realm's configuration to import at startup using the withRealmImportFile method from the KeycloakContainer object.

3.3. Spring Boot Testing Configuration

Now, let's launch the Keycloak container at the start of our tests. It uses a random port. So we need to override the keycloak.auth-server-url configuration defined in our once started. For this, we'll implement a callback interface triggered by Spring just before refreshing the context:

static class Initializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {

    public void initialize(ConfigurableApplicationContext configurableApplicationContext) {
        TestPropertyValues.of("keycloak.auth-server-url=" + keycloak.getAuthServerUrl())

We also need to tell Spring to use this class to initialize its context. Let's add this annotation at the class level:

@ContextConfiguration(initializers = { IntegrationTest.Initializer.class })

4. Creating Integration Tests

Now that we have our main test class responsible for launching our Keycloak container and configuring Spring properties, let's create an integration test calling our User controller.

4.1. Getting an Access Token

First, let's add to our abstract class IntegrationTest a method for requesting a token with Jane Doe's credentials:

URI authorizationURI = new URIBuilder(keycloak.getAuthServerUrl() + "/realms/baeldung/protocol/openid-connect/token").build();
WebClient webclient = WebClient.builder().build();
MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
formData.put("grant_type", Collections.singletonList("password"));
formData.put("client_id", Collections.singletonList("baeldung-api"));
formData.put("username", Collections.singletonList("[email protected]"));
formData.put("password", Collections.singletonList("s3cr3t"));

String result =

Here, we're using Webflux's WebClient to post a form containing the different parameters required to get an access token.

Finally, we'll parse the Keycloak server response to extract the token from it. Specifically, we generate a classic authentication string containing the Bearer keyword, followed by the content of the token, ready to be used in a header:

JacksonJsonParser jsonParser = new JacksonJsonParser();
return "Bearer " + jsonParser.parseMap(result)

4.2. Creating an Integration Test

Let's quickly set up integration tests against our configured Keycloak container. We'll be using RestAssured and Hamcrest for our test. Let's add the rest-assured dependency:


We can now create our test using our abstract IntegrationTest class:

void givenAuthenticatedUser_whenGetMe_shouldReturnMyInfo() {

    given().header("Authorization", getJaneDoeBearer())
      .body("username", equalTo("janedoe"))
      .body("lastname", equalTo("Doe"))
      .body("firstname", equalTo("Jane"))
      .body("email", equalTo("[email protected]"));

As a result, our access token, fetched from Keycloak, is added to the request's Authorization header.

5. Conclusion

In this article, we set up integration tests against an actual Keycloak, managed by Testcontainers. We imported a realm configuration to have a preconfigured environment each time we launch the test phase.

As usual, all the code samples used in this article can be found over on GitHub.

Security bottom

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

Security footer banner
Inline Feedbacks
View all comments