Keycloak Configuration Samples

This directory contains Keycloak realm and client configurations for the HelpDev platform.

Reference

These configurations implement patterns defined in:

• PRD Section 9: Identity and Access Management (Keycloak)
• PRD Section 5.2: platform-keycloak repository structure

Structure

keycloak/
├── realms/
│   ├── helpdev-platform/     # Realm for platform tools (Argo CD, Grafana, Backstage)
│   │   └── realm.json
│   └── helpdev-services/     # Realm for service-to-service authentication
│       └── realm.json
├── clients/
│   ├── argocd.json           # Argo CD OIDC client
│   ├── grafana.json          # Grafana OIDC client
│   └── backstage.json        # Backstage OIDC client
└── README.md

Realms

helpdev-platform

Realm for platform collaborators and tools:

• Purpose: SSO for platform tools (Argo CD, Grafana, Backstage)
• Identity Provider: GitHub (organization-based access)
• Roles:
  • platform-admin: Full access to all platform tools
  • platform-viewer: Read-only access to platform tools
  • developer: Standard developer access
  • secrets-admin: Full access to secrets management
  • secrets-manager: Domain-scoped secrets management

helpdev-services

Realm for service-to-service authentication:

• Purpose: Client credentials flow for microservices
• Client Scopes:
  • api-read: Read access to APIs
  • api-write: Write access to APIs
  • service-roles: Service-specific roles

Clients

argocd.json

OIDC client for Argo CD:

• Flow: Authorization Code with PKCE
• Groups Claim: Enabled for RBAC
• Redirect URIs: Production and HML environments

grafana.json

OIDC client for Grafana:

• Flow: Authorization Code with PKCE
• Role Mapping: Realm roles mapped to Grafana roles
• Groups Claim: Enabled for team-based dashboards

backstage.json

OIDC client for Backstage:

• Flow: Authorization Code with PKCE
• Service Account: Enabled for backend operations
• Authorization Services: Enabled for fine-grained permissions

Environment Variables

The configurations use environment variables for sensitive values:

Variable	Description
${DOMAIN}	Base domain (e.g., helpdev.io)
${GITHUB_CLIENT_ID}	GitHub OAuth App Client ID
${GITHUB_CLIENT_SECRET}	GitHub OAuth App Client Secret
${ARGOCD_CLIENT_SECRET}	Argo CD OIDC client secret
${GRAFANA_CLIENT_SECRET}	Grafana OIDC client secret
${BACKSTAGE_CLIENT_SECRET}	Backstage OIDC client secret
${SMTP_HOST}	SMTP server host
${SMTP_PORT}	SMTP server port
${SMTP_USER}	SMTP username
${SMTP_PASSWORD}	SMTP password

Usage

Import with keycloak-config-cli

# Import realm
docker run --rm \
  -e KEYCLOAK_URL=https://auth.helpdev.io \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=$KEYCLOAK_ADMIN_PASSWORD \
  -e IMPORT_PATH=/config \
  -v $(pwd)/realms:/config \
  adorsys/keycloak-config-cli:latest

Import clients

Clients should be imported after the realm is created:

# Using kcadm.sh
kcadm.sh config credentials --server https://auth.helpdev.io --realm master --user admin
kcadm.sh create clients -r helpdev-platform -f clients/argocd.json
kcadm.sh create clients -r helpdev-platform -f clients/grafana.json
kcadm.sh create clients -r helpdev-platform -f clients/backstage.json

GitOps Sync

These configurations are synchronized to Keycloak via GitOps:

1. Argo CD watches the platform-keycloak repository
2. keycloak-config-cli runs as a Kubernetes Job after Keycloak deployment
3. Configuration changes are applied automatically on sync

Sync Flow

Git Commit → Argo CD Sync → keycloak-config-cli Job → Keycloak Updated

Multi-Region Strategy

Per PRD Section 9.2:

• Each region has its own Keycloak instance
• Configuration (realms, clients) is synchronized via Git
• Runtime data (sessions, tokens) is isolated per region

Synced via Git	Isolated per Region
Realm definitions	User sessions
Client configurations	Refresh tokens
Roles and permissions	Audit logs
Identity providers	RDS database

Security Considerations

1. PKCE: All clients use PKCE for enhanced security
2. Client Secrets: Stored in AWS Secrets Manager, injected at runtime
3. SSL: Required for all external connections
4. Brute Force Protection: Enabled on all realms
5. Audit Logging: Enabled for all authentication events

Maintenance

Rotate Client Secrets

# Generate new secret
NEW_SECRET=$(openssl rand -base64 32)

# Update in AWS Secrets Manager
aws secretsmanager update-secret \
  --secret-id helpdev/prod/us-east-1/platform/keycloak/argocd-client-secret \
  --secret-string "$NEW_SECRET"

# Update in Keycloak
kcadm.sh update clients/<client-uuid> -r helpdev-platform -s secret="$NEW_SECRET"

Add New Client

1. Create JSON file in clients/ directory
2. Commit and push to Git
3. Argo CD syncs the change
4. keycloak-config-cli imports the new client

References

• Keycloak Documentation
• keycloak-config-cli
• PRD Section 9: Identity and Access Management