Customization
6 minute read
These docs are intended for demonstrating how to customize the uds-core Identity (Keycloak) deployment by updating/changing the config image.
Testing custom image in UDS Core
Build a new image
# create a dev image uds-core-config:keycloak
uds run dev-build
# optionally, retag and publish to temporary registry for testing
docker tag uds-core-config:keycloak ttl.sh/uds-core-config:keycloak
docker push ttl.sh/uds-core-config:keycloak
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
# build and deploy uds-core
uds run test-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:
uds run dev-theme
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
.
Note
Be aware that changing values in the realm may also need be to updated throughout the configuration of Keycloak and Authservice in uds-core
. For example, changing the realm name will break a few different things within Keycloak unless those values are changed in uds-core
as well.
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:
${REALM_GOOGLE_IDP_ENABLED:false}
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:
overrides:
keycloak:
keycloak:
values:
path: realmInitEnv
value:
GOOGLE_IDP_ENABLED: true
GOOGLE_IDP_ID: <fill in value here>
GOOGLE_IDP_SIGNING_CERT: <fill in value here>
GOOGLE_IDP_NAME_ID_FORMAT: <fill in value here>
GOOGLE_IDP_CORE_ENTITY_ID: <fill in value here>
GOOGLE_IDP_ADMIN_GROUP: <fill in value here>
GOOGLE_IDP_AUDITOR_GROUP: <fill in value here>
EMAIL_VERIFICATION_ENABLED: true
OTP_ENABLED: true
TERMS_AND_CONDITIONS_ENABLED: true
PASSWORD_POLICY: <fill in value here>
X509_OCSP_FAIL_OPEN: true
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
[req] default_bits = 2048 default_keyfile = key.pem distinguished_name = req_distinguished_name req_extensions = req_ext x509_extensions = v3_ext [req_distinguished_name] countryName = Country Name (2 letter code) countryName_default = US stateOrProvinceName = State or Province Name (full name) stateOrProvinceName_default = Colorado localityName = Locality Name (eg, city) localityName_default = Colorado Springs organizationName = Organization Name (eg, company) organizationName_default = Defense Unicorns commonName = Common Name (e.g. server FQDN or YOUR name) commonName_default = uds.dev [req_ext] subjectAltName = @alt_names [v3_ext] subjectAltName = @alt_names [alt_names] DNS.0 = *.uds.dev
# Generates new authorized_certs.zip uds run regenerate-test-pki
Update Dockerfile and build image
Update CA_ZIP_URL
in Dockerfile to refer to the generated authorized_certs.zip
ARG CA_ZIP_URL=authorized_certs.zip
Build config image
# build image
uds run dev-build
Note
If you’re getting errors from the ca-to-jks.sh script, verify your zip folder is in the correct directory.
Configure Istio Gateways CACERT in UDS Core
# In `uds-core` create cacert from the new identity-config image
uds run -f src/keycloak/tasks.yaml cacert --set IMAGE_NAME=<identity config image> --set VERSION=<identity config image version>
# Update tenant and admin gateway with generated cacerts
uds run -f src/keycloak/tasks.yaml dev-cacert
Deploy UDS Core with new uds-identity-config
See Testing custom image in UDS Core
Verify Istio Gateway configuration
# Verify the "Acceptable client certificate CA names"
openssl s_client -connect sso.uds.dev:443
Custom Plugin
Note
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.
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
authenticationFlowUpdate 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
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:
uds run build-zarf-pkg
Feedback
Was this page helpful?