Customization

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

• Official Keycloak Theme Docs
• Official Keycloak Theme Github

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:

1. Execute this command:

      uds run dev-theme

2. 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
               ACCESS_TOKEN_LIFESPAN: 600
               SSO_SESSION_LIFESPAN_TIMEOUT: 1200
               SSO_SESSION_MAX_LIFESPAN: 36000
               USERNAME_PASSWORD_AUTH_ENABLED: true
               X509_AUTH_ENABLED: true
               SOCIAL_AUTH_ENABLED: true
               DISABLE_REGISTRATION_FIELDS: true

These environment variables can be found in the realm.json.

Customize Session and Access Token Timeouts

The SSO_SESSION_IDLE_TIMEOUT specifies how long a session remains active without user activity, while the ACCESS_TOKEN_LIFESPAN defines the validity duration of an access token before it requires refreshing. The SSO_SESSION_MAX_LIFESPAN determines the maximum duration a session can remain active, regardless of user activity.

To ensure smooth session management, configure the idle timeout to be longer than the access token lifespan (e.g., 10 minutes idle, 5 minutes lifespan) so tokens can be refreshed before the session expires, and ensure the max lifespan is set appropriately (e.g., 8 hours) to enforce session limits. Misalignment, such as setting a longer token lifespan than the idle timeout or not aligning the max lifespan with session requirements, can result in sessions ending unexpectedly or persisting longer than intended.

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](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.

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

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