Skip to content

Customization

Testing custom image in UDS Core

Build a new image

Terminal window
# 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:

Deploy UDS Core

Terminal window
# 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:

  1. Execute this command:

    Terminal window
    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.

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.

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
  • Terminal window
    # 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

Terminal window
ARG CA_ZIP_URL=authorized_certs.zip

Build config image

Terminal window
# build image
uds run dev-build

Configure Istio Gateways CACERT in UDS Core

Terminal window
# 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>
Terminal window
# 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

Terminal window
# Verify the "Acceptable client certificate CA names"
openssl s_client -connect sso.uds.dev:443

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

Terminal window
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:

Terminal window
uds run build-zarf-pkg

Feedback

Was this page helpful?
Yes
No