Skip to content

Keycloak Plugin

A Keycloak plugin provides additional custom logic to our Keycloak deployment. Below is a table of the current implemented Custom Keycloak Implementations and how to interact with them.

Current Custom Implementations

NameTypeDescription
Group AuthenticationAuthenticatorDefine Keycloak group membership that is required to access an application. Additional documentation and E2E test.
Register Event ListenerEventListenerRegistration Event Listener to generate a unique id for each user that will be used as a mattermostId. E2E test. See Warnings below regarding this implementation.
JSON Log Event ListenerEventListenerJSON Log Event listener converts Keycloak event logs into json strings for ease of use in Logging applications like Grafana.
User Group Path MapperOpenID MapperSome application break when using a forward slash in the group naming, this mapper removes the leading slash and creates a new groups claim called bare-groups. See Warnings below regarding the use of this plugin.
User AWS SAML Group MapperSAML MapperAmazon AppStream applications expect a specific group claim format when using Keycloak to pass authentication. This mapper allows for customizing the new attribute name field that will show up in SAML Requests that will contain the necessary concatenated groups string: /parent-group/child-group1:/parent-group/child-group2.

Warnings

Requirements

Working on the plugin requires JDK17+ and Maven 3.5+.

Terminal window
# local java version
java -version
# loval maven version
mvn -version

Plugin Testing with Keycloak

After making changes to the plugin code and verifying that unit tests are passing ( and hopefully writing some more ), test against Keycloak.

See the New uds-identity-config Image section in the CUSTOMIZE.md for building, publishing, and using the new image with uds-core.

Plugin Unit Testing / Code Coverage

The maven surefire and jacoco plugins are configured in the pom.xml.

Some important commands that can be used when developing/testing on the plugin:

CommandDescription
mvn clean installCleans up build artifacts and then builds and installs project into local maven repository.
mvn clean testCleans up build artifacts and then compiles the source code and runs all tests in the project.
mvn clean test -Dtest=com.defenseunicorns.uds.keycloak.plugin.X509ToolsTestSame as mvn clean test but instead of running all tests in project, only runs the tests in designated file.
mvn surefire-report:reportThis command will run the mvn clean test and then generate the surefire-report.html file in target/site
mvn clean verifyClean project, run tests, and generate both surefire and jacoco reports

Viewing the Test Reports

Terminal window
# maven command from src/plugin directory
mvn clean verify

Open the src/plugin/target/site/surefire-report.html file in your browser to view the surefire test report.

Open the src/plugin/target/site/jacoco/index.html file in your browser to view the unit test coverage report generated by jacoco.

Both reports will hot reload each time they are regenerated, no need to open each time.