Reference: Keycloak as a Unified IAM Broker

Introduction

As organizations scale their Identity and Access Management (IAM) systems, managing multiple tenants, identity providers, clients, and configurations becomes increasingly complex.

Manual configuration through the Keycloak UI or procedural scripting via APIs leads to:

To solve this, automation becomes essential.

In this article, we explore:

1. What is Keycloak Admin API?

The Keycloak Admin REST API is an interface provided by Keycloak to programmatically manage:

Example: Create a Realm

POST /admin/realms
Authorization: Bearer <token>
Content-Type: application/json

{
  "realm": "demo-realm",
  "enabled": true
}

How Admin API Works

mermaid-diagram (6)

Challenges with Admin API

❌ Imperative (step-by-step execution)

❌ Requires orchestration (ordering matters)

❌ Not idempotent (duplicate runs may fail)

❌ Hard to maintain at scale

❌ Complex error handling

2. What is KeycloakConfigCLI?

KeycloakConfigCLI is a declarative tool that allows you to configure Keycloak using:

Instead of writing API calls, you define the desired final state, and the CLI applies it.

How It Works

Bash:
keycloak-config-cli --import
mermaid-diagram (7)

Example: Realm Configuration

{
  "realm": "demo-realm",
  "enabled": true,
  "clients": [
    {
      "clientId": "demo-client",
      "protocol": "openid-connect"
    }
  ]
}

3. Template-Driven Tenant Provisioning

Problem

Onboarding multiple tenants manually leads to:

Solution: Template-Driven Approach

Instead of creating tenants manually, define a reusable template:

mermaid-diagram (4)

Template Example

realm: ${REALM_NAME}
enabled: true

clients:
  - clientId: ${CLIENT_ID}
    protocol: openid-connect
    redirectUris:
      - ${REDIRECT_URI}

identityProviders:
  - alias: ${IDP_ALIAS}
    providerId: saml
    config:
      entityId: ${ENTITY_ID}

Dynamic Variables

VariableDescription
${REALM_NAME}Tenant-specific realm
${CLIENT_ID}Client identifier
${IDP_ALIAS}Identity provider name
${ENTITY_ID}SAML entity

Tenant Onboarding Workflow

Template → Replace variables → Apply CLI → Tenant created

Example Execution

export REALM_NAME=tenant1
export CLIENT_ID=tenant1-client

keycloak-config-cli --import

4. Multi-Tenant Provisioning Using Templates

mermaid-diagram (5)

Folder Structure

keycloak-config/
├── base-template.yaml
├── tenants/
│   ├── tenant1.env
│   ├── tenant2.env

Execution Script

for tenant in tenants/*.env
do
  source $tenant
  keycloak-config-cli --import
done

Result

✔ Multiple tenants created automatically

✔ Consistent configuration

✔ Zero manual UI work

5. KeycloakConfigCLI vs Admin API

FeatureAdmin APIKeycloakConfigCLI
ApproachImperativeDeclarative
Idempotency❌ No✔ Yes
ComplexityHighLow
CI/CD FriendlyLimitedExcellent
MaintenanceHardEasy
Scaling TenantsDifficultSimple
Error HandlingManualBuilt-in
mermaid-diagram (3)

6. When to Use Each Approach

Use Admin API when:

Use KeycloakConfigCLI when:

7. CI/CD Integration Example

- script: |
    docker run --rm \
      -e KEYCLOAK_URL=$(keycloakUrl) \
      -e KEYCLOAK_USER=$(username) \
      -e KEYCLOAK_PASSWORD=$(password) \
      -v $(System.DefaultWorkingDirectory)/config:/config \
      adorsys/keycloak-config-cli:latest

8. Benefits of Template-Driven Keycloak Automation

✔ Consistent environments (Dev / QA / Prod)

✔ Faster onboarding of new tenants

✔ Reduced manual effort

✔ Easy rollback using Git

✔ Improved auditability

9. Best Practices

10. Conclusion

Managing IAM configurations manually or through APIs becomes increasingly difficult as systems scale.

By using:

We can achieve:

KeycloakConfigCLI provides a powerful, scalable, and maintainable approach to managing identity infrastructure in modern applications.

KeycloakConfigCLI enables GitOps-style IAM configuration, allowing identity infrastructure to be treated as code, ensuring consistency, repeatability, and scalability across environments.