Configuration Reference
Keycloak environment variables
These environment variables are passed to the Keycloak container. In a Docker Compose setup they go in .env; in Kubernetes they are set in the Helm values and stored in Kubernetes Secrets.
Core configuration
| Variable | Required | Default | Description |
|---|---|---|---|
KC_HOSTNAME | Yes | — | Public hostname of the Keycloak server, e.g. auth.clickid.eu. Used in token issuers and redirect URLs. |
KC_HTTP_ENABLED | No | false | Set to true if TLS is terminated upstream (nginx, load balancer). Required when running behind a reverse proxy. |
KC_PROXY | No | none | Set to edge if TLS terminates at the ingress (most Kubernetes setups), or reencrypt if end-to-end TLS. |
KC_LOG_LEVEL | No | INFO | Log verbosity. Values: DEBUG, INFO, WARN, ERROR. Use DEBUG only for troubleshooting — very verbose. |
KC_HEALTH_ENABLED | No | true | Expose /health and /health/ready endpoints. Required by the Helm chart's liveness/readiness probes. |
KC_METRICS_ENABLED | No | false | Expose /metrics endpoint in Prometheus format. |
Database
| Variable | Required | Default | Description |
|---|---|---|---|
KC_DB | Yes | postgres | Database vendor. Only postgres is supported by ClickID. |
KC_DB_URL | Yes | — | Full JDBC URL, e.g. jdbc:postgresql://localhost:5432/keycloak. |
KC_DB_USERNAME | Yes | — | PostgreSQL username. |
KC_DB_PASSWORD | Yes | — | PostgreSQL password. Store in a Secret, not in plain config. |
KC_DB_POOL_MIN_SIZE | No | 5 | Minimum JDBC connection pool size. |
KC_DB_POOL_MAX_SIZE | No | 20 | Maximum JDBC connection pool size. Increase for high traffic. |
Admin credentials (bootstrap only)
These are used only for the initial admin account creation. After first startup, use the Keycloak Admin UI or Admin API to manage admin accounts.
| Variable | Required | Description |
|---|---|---|
KC_BOOTSTRAP_ADMIN_USERNAME | Yes (first run) | Initial Keycloak admin username. |
KC_BOOTSTRAP_ADMIN_PASSWORD | Yes (first run) | Initial Keycloak admin password. Change immediately after first login. |
Sector-ID Mapper
| Variable | Required | Description |
|---|---|---|
SECTOR_ID_PEPPER | Yes | HMAC-SHA256 key for sector-ID derivation. Must be identical across all cluster nodes. Never change after users exist. Generate with openssl rand -base64 32. |
The Sector-ID Mapper SPI reads this as KC_SPI_SECTOR_ID_PEPPER internally (the mapper configuration in the realm JSON references ${env.KC_SPI_SECTOR_ID_PEPPER}).
Email (SMTP)
| Variable | Required | Default | Description |
|---|---|---|---|
KC_SMTP_FROM | No | — | From address for outbound email, e.g. noreply@clickid.eu. |
KC_SMTP_HOST | No | — | SMTP server hostname. |
KC_SMTP_PORT | No | 587 | SMTP port. Use 465 for SMTPS, 587 for STARTTLS. |
KC_SMTP_USER | No | — | SMTP authentication username. |
KC_SMTP_PASSWORD | No | — | SMTP authentication password. |
KC_SMTP_SSL | No | false | Set to true for SMTPS (port 465). |
KC_SMTP_STARTTLS | No | true | Set to true for STARTTLS (port 587). |
In local development, all email is caught by Mailhog — no SMTP configuration is needed.
SP Portal environment variables
The SP Portal is a Nuxt 3 application. These variables configure its connection to Keycloak and control authentication.
| Variable | Required | Description |
|---|---|---|
NUXT_AUTH_SECRET | Yes | Secret key for NextAuth/nuxt-auth session encryption. Generate with openssl rand -base64 32. Rotate with care — rotating invalidates all active SP Portal sessions. |
NUXT_KEYCLOAK_ISSUER | Yes | Keycloak OIDC issuer URL for the SP Portal's own authentication. E.g. https://auth.clickid.eu/realms/clickid. |
NUXT_KEYCLOAK_CLIENT_ID | Yes | OIDC client ID for the SP Portal app in Keycloak. Default: sp-portal. |
NUXT_KEYCLOAK_CLIENT_SECRET | Yes | OIDC client secret for the SP Portal. Store in a Secret. |
NUXT_KC_ADMIN_URL | Yes | Keycloak Admin REST API base URL. E.g. https://auth.clickid.eu. |
NUXT_KC_ADMIN_CLIENT_ID | Yes | Client ID with admin privileges for realm management. Default: sp-portal-admin. |
NUXT_KC_ADMIN_CLIENT_SECRET | Yes | Client secret for the admin client. Store in a Secret. |
NUXT_KC_SANDBOX_REALM | No | Name of the sandbox realm. Default: clickid-sandbox. |
NUXT_KC_LIVE_REALM | No | Name of the live realm. Default: clickid. |
NUXT_SECTOR_ID_PEPPER | No | If set, the SP Portal can display sector-ID derivation examples in the UI. Should match the IdP pepper. Handle with care. |
NUXT_PUBLIC_KEYCLOAK_URL | Yes | Public-facing Keycloak URL shown in the portal UI and used for metadata URL generation. E.g. https://auth.clickid.eu. |
Helm values reference
The Helm chart exposes these key values. Set them in a values.yaml file or via --set flags.
Keycloak
| Value | Type | Default | Description |
|---|---|---|---|
keycloak.replicas | integer | 1 | Number of Keycloak pod replicas. Set to 2 or more for HA. |
keycloak.hostname | string | — | Public hostname, e.g. auth.clickid.eu. Mapped to KC_HOSTNAME. |
keycloak.admin.username | string | admin | Bootstrap admin username. |
keycloak.admin.password | string | — | Bootstrap admin password. Stored in a Kubernetes Secret. |
keycloak.db.password | string | — | PostgreSQL password. Stored in a Kubernetes Secret. |
keycloak.sectorIdPepper | string | — | Sector-ID HMAC key. Stored in a Kubernetes Secret. |
keycloak.existingSecret | string | "" | Name of an existing Kubernetes Secret containing all Keycloak credentials. Use with External Secrets Operator. If set, individual credential values are ignored. |
keycloak.image.repository | string | ghcr.io/clickid/keycloak | Container image repository. |
keycloak.image.tag | string | latest | Container image tag. Pin this in production. |
keycloak.resources.requests.memory | string | 768Mi | Keycloak memory request. |
keycloak.resources.limits.memory | string | 1.5Gi | Keycloak memory limit. |
keycloak.ingress.enabled | bool | true | Create an Ingress resource for Keycloak. |
keycloak.ingress.annotations | map | {} | Ingress annotations, e.g. cert-manager.io/cluster-issuer. |
SP Portal
| Value | Type | Default | Description |
|---|---|---|---|
spPortal.hostname | string | — | Public hostname, e.g. portal.clickid.eu. |
spPortal.authSecret | string | — | NUXT_AUTH_SECRET value. Stored in a Kubernetes Secret. |
spPortal.keycloak.clientSecret | string | — | OIDC client secret. Stored in a Kubernetes Secret. |
spPortal.keycloakAdmin.clientSecret | string | — | Admin client secret. Stored in a Kubernetes Secret. |
spPortal.image.repository | string | ghcr.io/clickid/sp-portal | Container image repository. |
spPortal.image.tag | string | latest | Container image tag. |
spPortal.ingress.enabled | bool | true | Create an Ingress resource for the SP Portal. |
spPortal.ingress.annotations | map | {} | Ingress annotations. |
PostgreSQL
The embedded PostgreSQL is provided by the Bitnami PostgreSQL subchart.
| Value | Type | Default | Description |
|---|---|---|---|
postgresql.enabled | bool | true | Deploy the embedded PostgreSQL. Set to false to use an external database. |
postgresql.auth.database | string | keycloak | Database name. |
postgresql.auth.username | string | keycloak | Database username. |
postgresql.auth.password | string | — | Database password. |
postgresql.primary.persistence.size | string | 8Gi | PVC size for PostgreSQL data. |
External database
For production at scale, consider using an external managed PostgreSQL (e.g. AWS RDS, Azure Database for PostgreSQL, or a self-hosted Patroni cluster) with postgresql.enabled=false and configuring keycloak.db.* values manually.