• Stars
    star
    343
  • Rank 123,371 (Top 3 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created almost 5 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Testcontainer implementation for Keycloak IAM & SSO.

Keycloak Testcontainer

A Testcontainers implementation for Keycloak SSO.

CI build Maven Central

IMPORTANT!!!

This version only handles the new Quarkus distribution of Keycloak (version 17+).
For Keycloak-Legacy (Wildfly-based distro), see version 1.x branch.

How to use

The @Container annotation used here in the readme is from the JUnit 5 support of Testcontainers. Please refer to the Testcontainers documentation for more information.

Default

Simply spin up a default Keycloak instance:

@Container
KeycloakContainer keycloak = new KeycloakContainer();

Custom image

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

@Container
KeycloakContainer keycloak = new KeycloakContainer("quay.io/keycloak/keycloak:21.0");

Realm Import

Power up a Keycloak instance with one or more existing realm JSON config files (from classpath):

@Container
KeycloakContainer keycloak = new KeycloakContainer()
    .withRealmImportFile("/test-realm.json");

or

    .withRealmImportFiles("/test-realm-1.json", "/test-realm-2.json");

Initial admin user credentials

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

@Container
KeycloakContainer keycloak = new KeycloakContainer()
    .withAdminUsername("myKeycloakAdminUser")
    .withAdminPassword("tops3cr3t");

Getting an admin client and other information from the testcontainer

You can get an instance of org.keycloak.admin.Keycloak admin client directly from the container, using

org.keycloak.admin.Keycloak keycloakAdmin = keycloakContainer.getKeycloakAdminClient();

The admin client is configured with current admin credentials.

The org.keycloak:keycloak-admin-client package is now a transitive dependency of this project, ready to be used by you in your tests, no more need to add it on your own.

You can also obtain several properties from the Keycloak container:

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

with these properties, you can create e.g. a custom org.keycloak.admin.client.Keycloak object to connect to the container and do optional further configuration:

Keycloak keycloakAdminClient = KeycloakBuilder.builder()
    .serverUrl(keycloak.getAuthServerUrl())
    .realm("master")
    .clientId("admin-cli")
    .username(keycloak.getAdminUsername())
    .password(keycloak.getAdminPassword())
    .build();

Context Path

As Keycloak now comes with the default context path /, you can set your custom context path, e.g. for compatibility reasons to previous versions, with:

@Container
KeycloakContainer keycloak = new KeycloakContainer()
    .withContextPath("/auth/");

TLS (SSL) Usage

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

Built-in TLS Keystore

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:

@Container
KeycloakContainer keycloak = new KeycloakContainer().useTls();

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

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:

@Container
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.

Custom TLS Keystore

Last but not least, you can also provide your own keystore file for usage in this Testcontainer:

@Container
KeycloakContainer keycloak = new KeycloakContainer()
    .useTlsKeystore("your_custom.jks", "password_for_your_custom_keystore");

See also KeycloakContainerHttpsTest.shouldStartKeycloakWithCustomTlsKeystore.

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

Features

You can enable and disable features on your Testcontainer:

@Container
KeycloakContainer keycloak = new KeycloakContainer()
    .withFeaturesEnabled("docker", "scripts", "...")
    .withFeaturesDisabled("authorization", "impersonation", "...");

Testing Custom Extensions

To ease extension testing, you can tell the Keycloak Testcontainer to detect extensions in a given classpath folder. This allows to test extensions directly in the same module without a packaging step.

If you have your Keycloak extension code in the src/main/java folder, then the resulting classes will be generated to the target/classes folder. To test your extensions you just need to tell KeycloakContainer to consider extensions from the target/classes folder.

Keycloak Testcontainer will then dynamically generate a packaged jar file with the extension code that is then picked up by Keycloak.

KeycloakContainer keycloak = new KeycloakContainer()
    .withProviderClassesFrom("target/classes");

See also KeycloakContainerExtensionTest class.

Dependencies & 3rd-party Libraries

If you need to provide any 3rd-party dependency or library, you can do this with

List<File> libs = ...;
KeycloakContainer keycloak = new KeycloakContainer()
    .withProviderLibsFrom(libs);

You have to provide a list of resolvable Files.

Extending KeycloakContainer

In case you need a custom implementation of the default KeycloakContainer, you should inherit from ExtendableKeycloakContainer. This allows to set the generics and use your custom implementation without the need for type casts.

public class MyCustomKeycloakContainer extends ExtendableKeycloakContainer<MyCustomKeycloakContainer> {

	public MyCustomKeycloakContainer() {
		super();
	}

	public MyCustomKeycloakContainer(String dockerImageName) {
		super(dockerImageName);
	}
	
}

...

MyCustomKeycloakContainer keycloakContainer = new MyCustomKeycloakContainer()
    .withAdminPassword("password");

TIPP

If you want/need to use dependencies from e.g. Maven (or Gradle), you can use ShrinkWrap Resolvers. See, as an example, how this is used at the KeycloakContainerExtensionTest#shouldDeployProviderWithDependencyAndCallCustomEndpoint() test.

Setup

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

<dependency>
  <groupId>com.github.dasniko</groupId>
  <artifactId>testcontainers-keycloak</artifactId>
  <version>VERSION</version>
  <scope>test</scope>
</dependency>

Usage in your application framework tests

This info is not specific to the Keycloak Testcontainer, but using Testcontainers generally.

I mention it here, as I see people asking again and again on how to use it in their test setup, when they think they need to specify a fixed port in their properties or YAML files...
You don't have to!
But you have to read the Testcontainers docs and the docs of your application framework on testing resources!!

Spring (Boot)

Dynamic context configuration with context initializers is your friend. In particular, look for @ContextConfiguration and ApplicationContextInitializer<ConfigurableApplicationContext>:

Quarkus

Read the docs about the Quarkus Test Resources and use @QuarkusTestResource with QuarkusTestResourceLifecycleManager

Others

Consult the docs of your application framework testing capabilities on how to dynamically configure your stack for testing!

YouTube Video about Keycloak Testcontainers

Testcontainers & Keycloak version compatiblity

For Keycloak-Legacy (before Quarkus-based distro), see version 1.x branch

Testcontainers-Keycloak Testcontainers Keycloak
2.0.0 1.16.3 17.0.0
2.1.1 1.16.3 17.0.0
2.1.2 1.16.3 17.0.1
2.2.0 1.17.1 18.0.0
2.2.1 1.17.1 18.0.0
2.2.2 1.17.1 18.0.0
2.3.0 1.17.1 19.0.0
2.4.0 1.17.3 20.0.0
2.5.0 1.17.6 21.0

There might also be other possible version configurations which will work.

See also the Releases page for version and feature update notes.

Credits

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.

License

Apache License 2.0

Copyright (c) 2019-2022 Niko Köbler

See LICENSE file for details.

More Repositories

1

keycloak-reactjs-demo

Reference example for React.JS and Keycloak SSO integration.
JavaScript
475
star
2

keycloak-2fa-sms-authenticator

Keycloak Authentication Provider implementation to get a 2nd-factor authentication with a OTP/code/token send via SMS (through AWS SNS). Demo purposes only!
Java
337
star
3

keycloak-extensions-demo

Demos, examples and playground for Keycloak extensions, providers, SPI implementations, etc.
Java
306
star
4

keycloak-user-spi-demo

Simple in-memory User Storage Provider SPI implementation for Keycloak. Demo purposes only!
Java
68
star
5

keycloak-session-restrictor

Simple event-listener for Keycloak which restricts the current user sessions to one (last one wins) only. Demo purposes only!
Java
57
star
6

keycloak-springboot-demo

Demo for Spring Boot and Keycloak SSO integration.
HTML
46
star
7

keycloak-bookshop-demo

Demo for how to integrate Keycloak into Quarkus and React apps and services. All (most) kinds of authentication (web app, service account, client, bearer-only...)
Java
44
star
8

ozark-react

A ViewEngine for ReactJS templates for the Java EE MVC 1.0 reference implementation Ozark.
Java
44
star
9

meteor-chat

Simple chat application built on the Meteor JavaScript Platform.
JavaScript
26
star
10

soteria-demo-mvc

Custom MVC Demo for Java EE 8 Security API (JSR-375) RI Soteria
Java
23
star
11

keycloak-aws-ses-email-provider

Drop-in Email Provider SPI replacement for Keycloak to send emails via AWS Simple Email Service (SES). Demo purposes only
Java
22
star
12

quarkus-keycloak

Demos on how to secure a Quarkus service/app with proper Keycloak authentication & doing tests with Testcontainers-Keycloak project.
Java
19
star
13

keycloak-tokenmapper-example

Example Keycloak OIDC protocol token mapper - maps a random lucky number to tokens/info endpoint - demo purposes only!
Java
17
star
14

keycloak-spi-bom

Custom Keycloak SPI BOM for extension development, maintained by @dasniko
15
star
15

keycloak-javaee-demo

Demo for Java EE and Keycloak SSO integration.
Java
14
star
16

meteor-mqtt

Meteor MQTT client using mqtt package from NPM
JavaScript
14
star
17

keycloak-workshop

Ressourcen für @dasniko's Keycloak Workshop
FreeMarker
12
star
18

keycloak-docker-aws

CSS
10
star
19

wildfly-async-redis

Demo code for comparison of async Node.js and Wildfly services.
Java
10
star
20

react-redux-example

A small and simple example app, demonstrating how to use react and redux for building webapps.
JavaScript
10
star
21

testcontainers-mailhog

Simple Demo how to test SMTP in your project using Testcontainers and Mailhog.
Java
7
star
22

keycloak-workshop-light

Ressourcen für @dasniko's Keycloak Workshop für Einsteiger
FreeMarker
6
star
23

riding-the-nashorn

Shell
5
star
24

keycloak-dev-workshop

Ressourcen für @dasniko's Keycloak Extension Development Workshop
Java
4
star
25

gatling-playground

Scala
3
star
26

keycloak-authdemo

Java
3
star
27

soteria-demo-jaxrs

JAX-RS Demo for Java EE 8 Security API (JSR-375) RI Soteria
Java
3
star
28

js4j

Shell
3
star
29

ansible-role-java

2
star
30

quarkus-workshop-2

Java
2
star
31

peanuts-api

Java
2
star
32

avatar-twitterwall

Simple twitterwall built with Project Avatar on Nashorn with JavaScript only for a JavaEE environment.
JavaScript
2
star
33

tut3c-nodyn

JavaScript
2
star
34

ehcache-search-example

Some examples for using and performance of the Ehcache Search API.
Java
2
star
35

camel-oracleaq

EAI with Apache Camel and Oracle AQ
Java
2
star
36

lambda-bash-runtime

Shell
1
star
37

spring-graphql-demo

GraphQL demo project for Spring Boot
Java
1
star
38

nashorn-spock-jasmine

Examples for testing Nashorn JavaScript with Spock and/or Jasmine
Groovy
1
star
39

beer-as-a-service

Nodyn examples with using Vert.x eventbus
JavaScript
1
star
40

dasniko

1
star
41

camel

EAI with Apache Camel
Java
1
star
42

meteor-espruino

Demo Meteor application communicating with Espruino microcontroller, using node-espruino package from NPM.
JavaScript
1
star