Skip to content
Documentation
Using
Getting Started
Configuration

Configuration

Every Keycloak instance you manage requires a ProviderConfig resource that specifies how to connect to the Keycloak API.

Create a Credentials Secret

The provider needs credentials to authenticate with Keycloak. Create a Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-credentials
  namespace: crossplane-system
type: Opaque
stringData:
  credentials: |
    {
      "client_id": "admin-cli",
      "username": "admin",
      "password": "admin",
      "url": "https://keycloak.example.com",
      "base_path": "/auth",
      "realm": "master"
    }

Credential Fields

FieldRequiredDescription
urlYesKeycloak server URL (e.g., https://keycloak.example.com)
client_idYesOAuth2 client ID (typically admin-cli)
usernameConditionalAdmin username (required if not using client credentials)
passwordConditionalAdmin password (required if not using client credentials)
client_secretConditionalClient secret (for client credential grants)
realmNoRealm for authentication (defaults to master)
base_pathNoURL path prefix (e.g., /auth for older Keycloak versions)
root_ca_certificateNoCustom CA certificate for TLS verification

Alternative: Flat Secret Format

Instead of embedded JSON, you can use plain key-value pairs:

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-credentials
  namespace: crossplane-system
type: Opaque
stringData:
  client_id: "admin-cli"
  username: "admin"
  password: "admin"
  url: "https://keycloak.example.com"
  base_path: "/auth"
  realm: "master"

Create a ProviderConfig

Reference the secret in a ProviderConfig:

apiVersion: keycloak.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: keycloak-provider-config
spec:
  credentials:
    source: Secret
    secretRef:
      name: keycloak-credentials
      key: credentials
      namespace: crossplane-system

URL Validation Rules

The provider validates and normalizes URL fields:

  • url must be an absolute URL with scheme and host
  • Trailing slashes are removed automatically
  • base_path must be empty or start with /
  • base_path: "/" is normalized to an empty string
  • Query parameters and fragments are not allowed in URLs

Multiple Keycloak Instances

You can manage multiple Keycloak instances by creating separate ProviderConfig resources, each with their own credentials secret. Reference the appropriate config in each managed resource:

apiVersion: realm.keycloak.crossplane.io/v1alpha1
kind: Realm
metadata:
  name: my-realm
spec:
  forProvider:
    realm: "my-realm"
  providerConfigRef:
    name: keycloak-provider-config  # References a specific ProviderConfig

Next Steps

First Realm