Custom Keycloak Plugins

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

Name	Type	Description
Group Authentication	Authenticator	Define Keycloak group membership that is required to access an application. Additional documentation and E2E test.
Register Event Listener	EventListener	Registration 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 Listener	EventListener	JSON Log Event listener converts Keycloak event logs into json strings for ease of use in Logging applications like Grafana.
User Group Path Mapper	OpenID Mapper	Some 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 Mapper	SAML Mapper	Amazon 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

Note

When creating a user via ADMIN API or ADMIN UI, the REGISTER event is not triggered, resulting in no Mattermost ID attribute generation. This will need to be done manually via click ops or the api. An example of how the attribute can be set via api can be seen here.

Caution

Please use this scope only if you understand the implications of excluding full path information from group data. It is highly important to not use the bare-groups claim for protecting an application due to security vulnerabilities.

Requirements

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

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

Note

mvn commands will need to be executed from inside of the src/plugin directory

Note

There is a uds-cli task for running the mvn clean verify command: uds run dev-plugin.

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

Command	Description
mvn clean install	Cleans up build artifacts and then builds and installs project into local maven repository.
mvn clean test	Cleans 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.X509ToolsTest	Same as mvn clean test but instead of running all tests in project, only runs the tests in designated file.
mvn surefire-report:report	This command will run the mvn clean test and then generate the surefire-report.html file in target/site
mvn clean verify	Clean project, run tests, and generate both surefire and jacoco reports

Viewing the Test Reports

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

New Custom Plugin Development

Caution

This isn’t recommended, however can be achieved if necessary

Note

Making these changes iteratively and importing into Keycloak to create a new realm can help to alleviate typo’s and mis-configurations. This is also the quickest solution for testing without having to create,build,deploy with new images each time.

The plugin provides the auth flows that keycloak uses for x509 (CAC) authentication as well as some of the surrounding registration flows.

One nuanced auth flow is the creation of a Mattermost ID attribute for users. CustomEventListener is responsible for generating the unique ID.

Note

When creating a user via ADMIN API or ADMIN UI, the ‘REGISTER’ event is not triggered, resulting in no Mattermost ID attribute generation. This will need to be done manually via click ops or the api. An example of how the attribute can be set via api can be seen here.

Configuration

In addition, modify the realm for keycloak, otherwise the realm will require plugin capabilities for registering and authenticating users. In the current realm.json there is a few sections specifically using the plugin capabilities. Here is the following changes necessary:

• Remove all of the UDS ... authenticationFlows:

  • UDS Authentication
  • UDS Authentication Browser - Conditional OTP
  • UDS Registration
  • UDS Reset Credentials
  • UDS registration form

• Make changes to authenticationExecutions from the browser authenticationFlow:

  • Remove auth-cookie
  • Remove auth-spnego
  • Remove identity-provider-redirector
  • Update the remaining authenticationFlow
    • "requirement": "REQUIRED"
    • "flowAlias": "Authentication"

• Remove registration-profile-action authenticationExecution from the registration form authenticationFlow

• Update the realm flows:

  • "browserFlow": "browser"
  • "registrationFlow": "registration"
  • "resetCredentialsFlow": "reset credentials"

Disabling

If desired the Plugin can be removed from the identity-config image by commenting out these lines in the Dockerfile:

COPY plugin/pom.xml .
COPY plugin/src ../src

RUN mvn clean package