# Keycloak configuration

Use this page to understand the main Keycloak configuration fields used by Ripple Custody. The example shows one possible component configuration; your realm setup, identity-provider integration, resource values, hosts, and secrets depend on your deployment.

This page applies to on-premise deployments only. For current defaults and the full supported schema, use the configuration packaged with your release.

## What this config controls

Keycloak provides identity and access management for Ripple Custody. Deployment configuration controls the Keycloak service, resource values, database connectivity, admin credentials, secret references, and ingress exposure.

OIDC provider federation is configured in Keycloak after deployment. For the federation model and setup steps, see [Federated identity and SSO](/products/custody/identity-and-access/sso) and [Configure OIDC federation in Keycloak](/products/custody/identity-and-access/sso/keycloak-integration).

For Keycloak runtime controls configured outside the deployment values, see [Keycloak session limiting](/products/custody/identity-and-access/sso/keycloak-session-limiting) and [Keycloak inactivity timeout](/products/custody/identity-and-access/sso/keycloak-inactivity-timeout).

## Environment variables

| Variable | Description | Default or source |
|  --- | --- | --- |
| `KC_DB_SCHEMA` | Database schema name. | `openid` |
| `KC_DB_URL` | JDBC connection URL. | Secret |
| `KC_LOG_LEVEL` | Keycloak log level. | `info` |
| `KEYCLOAK_ADMIN` | Admin username. | `admin` |
| `KEYCLOAK_ADMIN_PASSWORD` | Admin password. | Secret |
| `KC_BOOTSTRAP_ADMIN_USERNAME` | Bootstrap admin username. | `admin` |
| `KC_BOOTSTRAP_ADMIN_PASSWORD` | Bootstrap admin password. | Secret |


Database, host, OAuth provider, and integration URLs are managed by the deployment configuration and should not be set manually unless your release explicitly exposes those fields.

## Component fields

Location: `components.keycloak`

| Field | Description |
|  --- | --- |
| `enabled` | Enables the Keycloak component. |
| `replicas` | Number of Keycloak replicas. |
| `resources.limits` | CPU and memory limits for the Keycloak pod. |
| `resources.requests` | CPU and memory requests for the Keycloak pod. |
| `secrets.psql.secretRef` | Secret reference for database connection values. |
| `secrets.kc.secretRef` | Secret reference for admin and bootstrap credentials. |
| `secrets.oidc-credentials.secretRef` | Secret reference for OIDC credentials. |
| `secrets.clients.secretRef` | Secret reference for internal client secrets. |
| `ingress.main` | Ingress settings for the Keycloak endpoint. |


Resource values are workload-dependent. Set them based on your expected authentication load and observed runtime behavior.

## Admin configuration

Location: `harmonize.keycloak`

| Field | Type | Description |
|  --- | --- | --- |
| `admin.name` | string | Keycloak admin username. |
| `admin.password` | string | Keycloak admin password. An empty value can be generated by the deployment process when supported. |
| `realmAdmin.name` | string | Realm admin username. |
| `realmAdmin.secret` | string | Realm admin secret. An empty value can be generated by the deployment process when supported. |


## Secrets

Keycloak admin credentials and database credentials are supplied through Kubernetes secrets. For the expected secret names and keys, see [Secret management for authentication](/products/custody/deployment/reference/auth-secrets).

Keycloak stores some realm and client configuration in its database. When rotating a client secret or identity-provider secret, update the value where Keycloak stores it and verify any Kubernetes secret consumed by dependent components. Updating only one side can leave the deployment with mismatched secrets.

## Database

Keycloak and OAuth use PostgreSQL for persistent storage. Each component uses its own schema. For database connection settings and schema requirements, see [PostgreSQL configuration](/products/custody/deployment/reference/postgresql).

If database usernames or passwords include reserved URL characters, encode them in connection strings before storing them in secrets.

## Example

This example shows one possible Keycloak component configuration:


```yaml
harmonize:
  keycloak:
    admin:
      name: "admin"
      password: ""
    realmAdmin:
      name: "realm-admin"
      secret: ""

components:
  keycloak:
    enabled: true
    replicas: 2
    resources:
      limits:
        cpu: 1000m
        memory: 512Mi
      requests:
        cpu: 100m
        memory: 128Mi
    secrets:
      psql:
        secretRef: keycloak-psql
      kc:
        secretRef: keycloak-kc
      oidc-credentials:
        secretRef: keycloak-oidc-credentials
      clients:
        secretRef: keycloak-clients
    ingress:
      main:
        enabled: true
        hosts:
          - host: "openid.example.com"
            paths:
              - path: /
                pathType: Prefix
        tls:
          - secretName: keycloak-tls
            hosts:
              - openid.example.com
```

## Related topics

- [OAuth server configuration](/products/custody/deployment/reference/oauth-server)
- [Federated identity and SSO](/products/custody/identity-and-access/sso)
- [Configure OIDC federation in Keycloak](/products/custody/identity-and-access/sso/keycloak-integration)
- [Secret management for authentication](/products/custody/deployment/reference/auth-secrets)
- [Networking configuration](/products/custody/deployment/reference/networking)
- [PostgreSQL configuration](/products/custody/deployment/reference/postgresql)
- [Genesis payload reference](/products/custody/governance/genesis/payload-reference)
- [Keycloak session limiting](/products/custody/identity-and-access/sso/keycloak-session-limiting)
- [Keycloak inactivity timeout](/products/custody/identity-and-access/sso/keycloak-inactivity-timeout)