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
Section titled “Current Custom Implementations”Name | Type | Description |
---|---|---|
Group Authentication | Authenticator | Requires Keycloak group membership to access an application. Controls when Terms and Conditions are displayed. More info and E2E test. |
Register Event Listener | EventListener | Generates a unique mattermostId for each user during registration. E2E test. |
JSON Log Event Listener | EventListener | Converts Keycloak event logs into JSON strings for logging applications like Grafana. |
User Group Path Mapper | OpenID Mapper | Removes leading slash from group names and creates a new bare-groups claim. |
User AWS SAML Group Mapper | SAML Mapper | Filters user groups to include only those with -aws- and concatenates them into a colon-separated string for SAML attribute. |
ClientIdAndKubernetesSecretAuthenticator | ClientAuthenticator | Authenticates a client using a Kubernetes secret. Used in the ClientIdAndKubernetesSecret authentication flow. |
UDSClientPolicyPermissionsExecutor | ClientPolicyExecutorProvider | Checks if a client has the necessary permissions to access a resource. Used in the UDSClientPolicyPermissions client policy. |
Security hardening
Section titled “Security hardening”The UDS Keycloak Plugin leverages Keycloak Client Policies to enforce security hardening for clients created by the UDS Operator. The configuration can be accessed under “Realm Settings” > “Client Policies” > “UDS Client Profile” > “uds-operator-permissions” and includes the following options:
Additional Allowed Protocol Mappers
- Specifies additional Protocol Mappers permitted for use by the packages.Use UDS Default Allowed Protocol Mappers
- When enabled, applies a predefined list of Protocol Mappers. Additional Protocol Mappers can be added using theAdditional Allowed Protocol Mappers
option.Additional Allowed Client Scopes
- Specifies additional Client Scopes permitted for use by the packages.Use UDS Default Client Scopes
- When enabled, applies a predefined list of Client Scopes. Additional Client Scopes can be added using theAdditional Allowed Client Scopes
option.
Terms and Conditions behavior
Section titled “Terms and Conditions behavior”The Group Authentication plugin controls when the Terms and Conditions are displayed to the user. By default, users are required to accept the Terms and Conditions once per session, meaning that if a user logs in with multiple Keycloak Clients, the Terms and Conditions are displayed only once. This behavior can be modified by adjusting the Authentication Flows in the Keycloak Admin Console and changing the “UDS Operator Group Authentication Validation” step settings. The plugin allows UDS Administrators to change the “Display Terms and Conditions only per user session” setting. Setting it to “false” will force users to accept the Terms and Conditions every time they log in.
Warnings
Section titled “Warnings”Requirements
Section titled “Requirements”Working on the plugin requires JDK17+ and Maven 3.5+.
# local java versionjava -version
# loval maven versionmvn -version
Plugin Testing with Keycloak
Section titled “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
Section titled “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:
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
Section titled “Viewing the Test Reports”# maven command from src/plugin directorymvn 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
Section titled “New Custom Plugin Development”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.
Configuration
Section titled “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
UDS Client Credentials
-
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
-
Remove
registration-profile-action
authenticationExecution from theregistration form
authenticationFlow -
Update the realm flows:
"browserFlow": "browser"
"registrationFlow": "registration"
"resetCredentialsFlow": "reset credentials"
"clientAuthenticationFlow": "clients"
Disabling
Section titled “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