Skip to content
A Testcontainer implementation for Keycloak SSO.
Java Shell
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
src disable log output by default Jan 15, 2020
.gitignore project setup Dec 13, 2019
LICENSE improve readme Dec 18, 2019

Keycloak Testcontainer

A Testcontainer implementation for Keycloak SSO.

How to use

Simply spin up a default Keycloak instance:

private KeycloakContainer keycloak = new KeycloakContainer();

Use another Keycloak Docker image/version than used in this Testcontainer:

private KeycloakContainer keycloak = new KeycloakContainer("jboss/keycloak:7.0.0");

Power up a Keycloak instance with an existing realm JSON config file (from classpath):

private KeycloakContainer keycloak = new KeycloakContainer()

Use different admin credentials than the defaut internal (admin/admin) ones:

private KeycloakContainer keycloak = new KeycloakContainer()

You can obtain several properties form the Keycloak container:

String authServerUrl = keycloak.getAuthServerUrl();
String adminUsername = keycloak.getAdminUsername();
String adminPassword = keycloak.getAdminPassword();

with these properties, you can create a org.keycloak.admin.client.Keycloak (Keycloak admin client, 3rd party dependency from Keycloak project) object to connect to the container and do optional further configuration:

Keycloak keycloakAdminClient = KeycloakBuilder.builder()

See also KeycloakContainerTest class.

TLS (SSL) Usage

You have several options to use HTTPS/TLS secured communication with your Keycloak Testcontainer.

Default Support

Plain Keycloak comes with a default Java KeyStore (JKS) with an auto-generated, self-signed certificate on first use. You can use this TLS secured connection, although your testcontainer doesn't know of anything TLS-related and returns the HTTP-only url with getAuthServerUrl(). In this case, you have to build the auth-server-url on your own, e.g. like this:

String authServerUrl = "https://localhost:" + keycloak.getHttpsPort() + "/auth";

See also KeycloakContainerHttpsTest.shouldStartKeycloakWithDefaultTlsSupport.

Built-in TLS Cert and Key

This Keycloak Testcontainer comes with built-in TLS certificate (tls.crt), key (tls.key) and Java KeyStore (tls.jks) files, located in the resources folder. You can use this configuration by only configuring your testcontainer like this:

private KeycloakContainer keycloak = new KeycloakContainer().useTls();

The password for the provided Java KeyStore file is changeit. See also KeycloakContainerHttpsTest.shouldStartKeycloakWithProvidedTlsCertAndKey.

The method getAuthServerUrl() will then return the HTTPS url.

Custom TLS Cert and Key

Of course you can also provide your own certificate and key file for usage in this Testcontainer:

private KeycloakContainer keycloak = new KeycloakContainer()
    .useTls("your_custom.crt", "your_custom.key");

See also KeycloakContainerHttpsTest.shouldStartKeycloakWithCustomTlsCertAndKey.

The method getAuthServerUrl() will also return the HTTPS url.


The release versions of this project are available at Maven Central. Simply put the dependency coordinates to your pom.xml (or something similar, if you use e.g. Gradle or something else):



Many thanks to the creators and maintainers of Testcontainers. You do an awesome job!

Same goes to the whole Keycloak team!

Kudos to @thomasdarimont for some inspiration for this project.


MIT License

Copyright (c) 2019 Niko Köbler

See LICENSE file for details.

You can’t perform that action at this time.