User guide

Keycloak Init lets application owners describe initial clients, users, identity providers, and identity provider mappers as JSON. A platform administrator runs the initializer with access to Keycloak and Kubernetes. There is no interactive interface or command-line configuration tool.

Prepare initialization data

Create four UTF-8 JSON files. Each file must contain an array of objects; use [] when you do not need objects of that type.

All four keys must be present in the initdata Secret. The current code's fallback for an absent key fails during JSON decoding. Files mounted into the container, including files under /data, are not read.

Keep names unique within each array. The initializer passes client, provider, and mapper objects directly to the Keycloak library; it does not validate their provider-specific fields. Use representations appropriate for your installed Keycloak version.

Clients

For example, clients.json can describe a browser application:

[
  {
    "clientId": "example-web",
    "name": "Example web application",
    "enabled": true,
    "protocol": "openid-connect",
    "publicClient": true,
    "standardFlowEnabled": true,
    "redirectUris": ["https://app.example.com/callback"],
    "webOrigins": ["https://app.example.com"]
  }
]

Replace the application URLs and choose client settings that match your application. clientId is required by the initializer. Other fields are passed through to Keycloak. Existing clients are skipped, including changes to redirect URIs, secrets, and enabled status.

Users

users.json uses the initializer's own user format:

[
  {
    "username": "example-user",
    "password": "REPLACE_WITH_A_UNIQUE_PASSWORD",
    "email": "example-user@example.com",
    "firstName": "Example",
    "lastName": "User",
    "admin": false
  }
]

New users are enabled. Additional fields such as enabled, emailVerified, credentials, groups, and arbitrary role mappings are not copied from the input. Use a JSON boolean for admin, not a quoted string.

Admin assignment in master uses the realm role named admin. In other realms, the initializer looks for a client role named exactly admin on realm-management. If the client or role is absent, it logs an error and leaves the user without that assignment. Ask an administrator to verify access; setting admin: true does not guarantee admin privileges.

Existing users receive no profile, password, or role changes from this file. An unsuccessful role assignment is also not retried for that user on later passes, because the user then already exists.

Identity providers and mappers

Use federated_auth.json for identity provider objects. Each object needs an alias for the initializer's existence check, plus the provider fields required by Keycloak, such as its providerId and provider-specific config.

Use federated_mappers.json for their mapper objects. Each mapper needs a non-empty identityProviderAlias and name, plus its Keycloak mapper type and configuration. Entries missing either name or alias are logged and skipped. The referenced provider must already exist or be included in federated_auth.json; providers are created before mappers.

For an installation without external identity providers, both files contain:

[]

These files configure identity providers and their mappers. The initializer has no separate LDAP/user-storage configuration workflow.

Validate and submit the files

From the project root, use the ignored tmp directory for local working data:

mkdir -p tmp/initdata
chmod 700 tmp tmp/initdata

Save the four files there, replace all example values, and restrict their file permissions. The following checks JSON syntax and verifies that each top-level value is an array of objects; it does not contact either service:

chmod 600 tmp/initdata/*.json
python3 - <<'PY'
import json
from pathlib import Path

for name in ("clients.json", "users.json", "federated_auth.json", "federated_mappers.json"):
    path = Path("tmp/initdata") / name
    data = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(data, list) or not all(isinstance(item, dict) for item in data):
        raise SystemExit(f"{name}: expected an array of objects")
    print(f"{name}: valid JSON array")
PY

Give the files to the platform administrator through your approved secret handling process. An authorized operator can create or update initdata as follows, replacing keycloak if a different namespace is used:

kubectl -n keycloak create secret generic initdata \
  --from-file=clients.json=tmp/initdata/clients.json \
  --from-file=users.json=tmp/initdata/users.json \
  --from-file=federated_auth.json=tmp/initdata/federated_auth.json \
  --from-file=federated_mappers.json=tmp/initdata/federated_mappers.json \
  --dry-run=client -o yaml | kubectl apply -f -

The files can contain passwords and provider/client secrets. Keep them out of version control and shared logs. The ignored local directory does not replace access controls or secure storage.

Apply changes and use the accounts

The initializer processes the realm, clients, users, identity providers, then mappers. After a successful pass it waits one hour before reading the Secrets again. An administrator can restart the Deployment to process additions sooner.

Changes to existing objects and removal of entries from the files do not update or delete Keycloak objects. Ask a Keycloak administrator to edit existing client settings, rotate user passwords, change roles, or remove accounts. Renaming an entry can create another object while leaving the original in place.

For a newly provisioned user, obtain the application URL, realm, username, and password through your administrator's approved channel. The initializer does not send welcome messages or provide an account portal. It does not request a password change on first login through a temporary credential, and it marks email as verified without an email-verification step. Other realm policies may still require actions at sign-in.

If login fails, ask the administrator to confirm that the realm is enabled, the expected user/client exists, and initialization completed. New realms start disabled. Operational checks are in the administrator guide.