Customization
Testing custom image in UDS Core
Build a new image
Update UDS Core references
The custom image reference will need to be update in a few places in the uds-core
repository:
- Update zarf.yaml to include updated image
- Specify
configImage
in Keycloak values.yaml - If the truststore has been updated, see gateway configuration instructions
Deploy UDS Core
See UDS Core for further details
Customizations
Add additional jars
Adding additional jars to Keycloak’s deployment is as simple as adding that jar to the src/extra-jars directory.
Adding new jars will require building a new identity-config image for uds-core.
See Testing custom image in UDS Core for building, publishing, and using the new image with uds-core
.
Once uds-core
has sucessfully deployed with your new image, viewing the Keycloak pod can provide insight into a successful deployment or not. Also describing the Keycloak pod, should display your new image being pulled instead of the default image defined here in the events section.
Customize Theme
Official Theming Docs
Changes can be made to the src/theme directory. At this time only Account and Login themes are included, but could be changed to include email, admin, and welcome themes as well.
Testing Changes
To test the identity-config
theme changes, a local running Keycloak instance is required.
Don’t have a local Keycloak instance? The simplest testing path is utilizing uds-core, specifically the dev-identity
task. This will create a k3d cluster with Istio, Pepr, Keycloak, and Authservice.
Once that cluster is up and healthy and after making theme changes:
-
Execute this command:
-
View the changes in the browser
Customizing Realm
The UDS Identity
realm is defined in the realm.json found in src/realm.json. This can be modified and will require a new uds-identity-config
image for uds-core
.
See the Testing custom image in UDS Core for building, publishing, and using the new image with uds-core
.
Templated Realm Values
Keycloak supports using environment variables within the realm configuration, see docs.
These environment variables have default values set in the realm.json that uses the following syntax:
In the uds-core keycloak values.yaml, the realmInitEnv
defines set of environment variables that can be used to configure the realm different from default values.
These environment variables will be created with a prefix REALM_
to avoid collisions with keycloak environment variables. If necessary to add additional template variables within the realm.json must be prefixed with REALM_
.
For example, this bundle override contains all the available overrides:
These environment variables can be found in the realm.json
identityProviders
section.
Customize Truststore
The default truststore is configured in a script and excuted in the Dockerfile. There is a few different ways the script could be customized.
- Change where the DoD CA zip file are pulled from., defualting to DOD UNCLASS certs but could be updated for local or another source.
- Change the Regex Exclusion Filter, used by the ca-to-jks script to exclude certain certs from being added to the final truststore.
- Change the truststore password
Build test authorized_certs.zip
Utilizing the regenerate-test-pki
task, you can create a test authorized_certs.zip
to use for the truststore.
To use the regenerate-test-pki
task:
-
Create
csr.conf
Update Dockerfile and build image
Update CA_ZIP_URL
in Dockerfile to refer to the generated authorized_certs.zip
Build config image
Configure Istio Gateways CACERT in UDS Core
Deploy UDS Core with new uds-identity-config
See Testing custom image in UDS Core
Verify Istio Gateway configuration
Custom Plugin
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](https://github.com/defenseunicorns/uds-identity-config/blob/main/src/plugin/src/main/java/com/defenseunicorns/uds/keycloak/plugin/eventListeners/RegisterEventListenerProvider.java is responsible for generating the unique ID.
Developing
See PLUGIN.md.
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
-
Remove
registration-profile-action
authenticationExecution from theregistration 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:
Building New Image with Updates
Once satisfied with changes and tested that they work, see Testing custom image in UDS Core for building, publishing, and using the new image with uds-core
.
Transport Custom Image with Zarf
For convenience, a Zarf package definition has been included to simplify custom image transport and install in air-gapped systems.
Build the Zarf package
Use the included UDS task to build the custom image and package it with Zarf: