Keycloak Bootstrapping Instructions

Introduction

This page describes the steps needed for setting up the Keycloak mtg-ers realm.

The setup is performed by a single unified script mtg-ers-realm.sh, executed via runSteps.sh. All provisioning is gated by feature flags; only the components explicitly enabled via environment variables will be created.

Starting from mtg-keycloak package version 26.4.5 and above, setup files are located under /usr/lib/mtg-keycloak/keycloak-setup.

Prerequisites

mtg-keycloak package for your Linux distribution must be already installed in your Linux system.
mtg-keycloak package for your Linux distribution must be already properly configured, connected with the database, started up and running.

Files

Inside /usr/lib/mtg-keycloak/keycloak-setup you will find:

mtg-ers-realm.sh      # unified setup script
runSteps.sh           # pipeline runner
mtg-ers-realm.env     # environment variable reference file
mTLS-clm.json         # mTLS config for CLM X.509 auth flow execution
mTLS-kms.json         # mTLS config for KMS X.509 auth flow execution

Feature Flags

All provisioning is controlled by feature flags. Set each flag to true to enable the corresponding component. Unset or empty means the component is skipped.

Flag Provisions

Flag	Provisions
`CREATE_REALM`	Base realm setup — realm creation, auth flow, client scopes, key provider, realm settings (steps 1–16)
`CARA_ENABLED`	CARA clients, roles, users, mTLS-cara auth flow execution (steps 20–33)
`KMS_ENABLED`	KMS roles, clients, admin user, mTLS-kms auth flow execution (steps 40–50)
`CLM_ENABLED` or `KMS_ENABLED`	Shared infrastructure — admin role, LDAP federation, admin_api_client, KC_ADMIN role, events (steps 34–39)
`CLM_ENABLED`	CLM clients, roles, admin user, protocol API clients, mTLS-clm auth flow execution (steps 68–86)

CREATE_REALM

Base realm setup — realm creation, auth flow, client scopes, key provider, realm settings (steps 1–16)

CARA_ENABLED

CARA clients, roles, users, mTLS-cara auth flow execution (steps 20–33)

KMS_ENABLED

KMS roles, clients, admin user, mTLS-kms auth flow execution (steps 40–50)

CLM_ENABLED or KMS_ENABLED

Shared infrastructure — admin role, LDAP federation, admin_api_client, KC_ADMIN role, events (steps 34–39)

CLM_ENABLED

CLM clients, roles, admin user, protocol API clients, mTLS-clm auth flow execution (steps 68–86)

Steps

1. Configure environment variables

Edit mtg-ers-realm.env. The file is grouped into sections. Fill in the values relevant to your deployment:

##############################################################################
# GENERAL — required for all deployments
##############################################################################
KEYCLOAK_URL=http://localhost:8080/auth
KEYCLOAK_ADMIN_USERNAME=admin
KEYCLOAK_ADMIN_USER_PASS=<admin-password>

# Gate flags — set to true to enable each component
CREATE_REALM=true
CARA_ENABLED=
KMS_ENABLED=
CLM_ENABLED=

EXT_DOMAIN=<your-external-domain>
MTLS_ENABLED=               # true | (empty = skip)
TRUSTSTORE_PATH=            # optional
TRUSTSTORE_PASSWORD=        # optional, required if TRUSTSTORE_PATH is set

ERS_ADMIN_API_CLIENT_ID=admin_api_client
ERS_ADMIN_API_CLIENT_SECRET=<secret>

KEYCLOAK_SMTPSERVER_HOST=<smtp-host>
KEYCLOAK_SMTPSERVER_PORT=1025
KEYCLOAK_SMTPSERVER_FROM=admin@example.com
# ... (see mtg-ers-realm.env for full list of SMTP vars)

##############################################################################
# CARA — required when CARA_ENABLED=true
##############################################################################
CARA_SERVER_CLIENT_SECRET=<secret>
CARA_ADMIN_UI_CLIENT_ROOT_URL=https://<your-domain>
CARA_ADMIN_UI_CLIENT_REDIRECT_URIS=["https://<your-domain>/*"]
CARA_ADMIN_UI_CLIENT_WEB_ORIGINS=["https://<your-domain>"]
CARA_ADMIN_USERNAME=caraadmin
CARA_ADMIN_USER_PASS=<password>

##############################################################################
# KMS — required when KMS_ENABLED=true
##############################################################################
KEYCLOAK_KMS_SERVER_CLIENT_SECRET=<secret>

##############################################################################
# CLM — required when CLM_ENABLED=true
##############################################################################
KEYCLOAK_CLM_SERVER_CLIENT_SECRET=<secret>
CLM_ADMIN_USERNAME=admin
CLM_ADMIN_USER_EMAIL=admin@example.com
CLM_ADMIN_USER_FIRSTNAME=Admin
CLM_ADMIN_USER_LASTNAME=User
CLM_ADMIN_USER_PASS=<password>
CLM_ACME_API_CLIENT_ID=acme_apiclient
CLM_ACME_API_CLIENT_SECRET=<secret>
CLM_SCEP_API_CLIENT_ID=scep_apiclient
CLM_SCEP_API_CLIENT_SECRET=<secret>
CLM_EST_API_CLIENT_ID=est_apiclient
CLM_EST_API_CLIENT_SECRET=<secret>
CLM_CMP_API_CLIENT_ID=cmp_apiclient
CLM_CMP_API_CLIENT_SECRET=<secret>
CLM_AEC_API_CLIENT_ID=aec_apiclient
CLM_AEC_API_CLIENT_SECRET=<secret>

2. Export variables and run

cd /usr/lib/mtg-keycloak/keycloak-setup
set -a; source ./mtg-ers-realm.env; set +a
./runSteps.sh ./mtg-ers-realm.sh

3. Run a specific step (troubleshooting)

./runSteps.sh -s 36 ./mtg-ers-realm.sh   # run only step 36
./runSteps.sh -f 34 ./mtg-ers-realm.sh   # run from step 34 onwards

These scripts are intended to run once during initial installation. Re-running them against an already-configured realm will result in errors (duplicate realm, clients, roles, etc.).