Secret management for authentication

Use this page to understand the Kubernetes secret names and keys used by the authentication components in Ripple Custody. The examples show possible secret shapes; your secret manager, namespace, rotation process, and credential values 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

Authentication services use Kubernetes secrets for database access, service credentials, OIDC integration, OAuth signing keys, and client secrets.

Some secrets are supplied by the deployment operator. Other secrets are generated or managed by the deployment configuration.

Secret fields

Keycloak secrets

Secret	Key	Description
`keycloak-psql`	`KC_DB_URL`	JDBC connection string for the Keycloak database schema.
`keycloak-psql`	`PG_CONN_URL`	PostgreSQL connection string used by Keycloak.
`keycloak-kc`	`KEYCLOAK_ADMIN`	Keycloak admin username.
`keycloak-kc`	`KEYCLOAK_ADMIN_PASSWORD`	Keycloak admin password.
`keycloak-kc`	`KC_BOOTSTRAP_ADMIN_USERNAME`	Bootstrap admin username.
`keycloak-kc`	`KC_BOOTSTRAP_ADMIN_PASSWORD`	Bootstrap admin password.
`keycloak-kc`	`KC_BOOTSTRAP_ADMIN_CLIENT_ID`	Bootstrap admin client ID.
`keycloak-oidc-credentials`	`OAUTH_SERVER_CLIENT_ID`	Client ID used by Keycloak to communicate with the OAuth server.
`keycloak-oidc-credentials`	`OAUTH_SERVER_CLIENT_SECRET`	Client secret used by Keycloak to communicate with the OAuth server.
`keycloak-clients`	Service client secrets	Internal service client secrets. This secret is managed automatically.

OAuth server secrets

Secret	Key	Description
`oauth-server`	`OAUTH_SERVER_KEY`	Private key used by the OAuth server.
`oauth-clients`	`OAUTH_CLIENTS`	JSON document containing OAuth client definitions.
`oauth-oidc-credentials`	`OAUTH_SERVER_CLIENT_ID`	Client ID used for OIDC integration.
`oauth-oidc-credentials`	`OAUTH_SERVER_CLIENT_SECRET`	Client secret used for OIDC integration.
`oauth-psql`	`POSTGRES_URL`	PostgreSQL connection string for the OAuth server database schema.

Constraints and relationships

Authentication secrets must exist in the namespace where the authentication components read them.
Secret values should be supplied through your normal secret-management process.
The keycloak-clients secret contains internal service client secrets and is managed automatically.
OAuth private key material must be valid private key data in the format expected by the OAuth server.
Connection string values must match the PostgreSQL host, database, credentials, and schema used by your deployment.

Example

This example shows a possible set of Kubernetes secrets for Keycloak and OAuth. Replace namespaces, connection strings, usernames, passwords, client secrets, and private key material with values from your own environment.

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-kc
  namespace: harmonize
type: Opaque
stringData:
  KEYCLOAK_ADMIN: "admin"
  KEYCLOAK_ADMIN_PASSWORD: "<strong-password>"
  KC_BOOTSTRAP_ADMIN_USERNAME: "admin"
  KC_BOOTSTRAP_ADMIN_PASSWORD: "<strong-password>"
  KC_BOOTSTRAP_ADMIN_CLIENT_ID: "<client-id>"
---
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-psql
  namespace: harmonize
type: Opaque
stringData:
  KC_DB_URL: "jdbc:postgresql://postgres:5432/harmonize?currentSchema=keycloak"
  PG_CONN_URL: "postgres://keycloak_user:<password>@postgres:5432/harmonize"
---
apiVersion: v1
kind: Secret
metadata:
  name: oauth-server
  namespace: harmonize
type: Opaque
stringData:
  OAUTH_SERVER_KEY: |
    -----BEGIN PRIVATE KEY-----
    <private-key-material>
    -----END PRIVATE KEY-----
---
apiVersion: v1
kind: Secret
metadata:
  name: oauth-psql
  namespace: harmonize
type: Opaque
stringData:
  POSTGRES_URL: "postgres://oauth_user:<password>@postgres:5432/harmonize?schema=oauth"

External secret managers

You can use an external secret manager to materialize the Kubernetes secrets that Ripple Custody expects. The provider-specific configuration belongs to your secret-manager tooling.

This example shows the expected pattern: map remote secret values to the Kubernetes secret keys listed above.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: oauth-server-key
  namespace: harmonize
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: <secret-store-name>
    kind: SecretStore
  target:
    name: oauth-server
    creationPolicy: Owner
  data:
    - secretKey: OAUTH_SERVER_KEY
      remoteRef:
        key: <remote-secret-name>
        property: private_key