Add cloud-native user provisioning for Keycloak mode

[michaelstingl]

Problem

Currently, users must be created manually in Keycloak through the UI or API. In a Kubernetes environment, it would be more cloud-native to declaratively define users through Helm values, ConfigMaps, or CRDs.

Current State

Users must be created by:

1. Logging into Keycloak admin console
2. Manually creating users through the UI
3. Or using Keycloak API/CLI after deployment

This doesn't follow Kubernetes declarative principles where infrastructure should be defined as code.

Expected Behavior

Users should be definable in a cloud-native way:

• Through Helm values during installation
• Via ConfigMaps that can be updated
• Using Kubernetes CRDs for full GitOps compatibility

Reference: opencloud-compose Pattern

The opencloud-compose repository includes pre-defined users in config/keycloak/opencloud-realm-autoprovisioning.dist.json:

{
  "users": [{
    "username": "admin",
    "firstName": "Admin",
    "email": "admin@example.org",
    "emailVerified": true,
    "enabled": true,
    "credentials": [{
      "type": "password",
      "value": "admin"
    }],
    "realmRoles": ["opencloudAdmin", "default-roles-opencloud"],
    "groups": ["/users"]
  }]
}

However, this uses hardcoded passwords, which is insecure for production.

Proposed Solution

Option 1: Helm Values (Simplest)

keycloak:
  users:
    - username: admin
      email: admin@example.com
      # Password from existing secret
      passwordSecret:
        name: admin-credentials
        key: password
      roles: 
        - opencloudAdmin
      groups:
        - /users
    - username: john
      email: john@example.com
      passwordSecret:
        name: john-credentials
        key: password
      groups:
        - /users
        - /developers

Option 2: ConfigMap-based (More Flexible)

apiVersion: v1
kind: ConfigMap
metadata:
  name: opencloud-users
  labels:
    app.kubernetes.io/component: keycloak-users
data:
  users.yaml: |
    users:
      - username: admin
        email: admin@example.com
        passwordSecretRef: admin-credentials
        roles: [opencloudAdmin]
        groups: [/users]

Option 3: CRDs (Most Cloud-Native)

apiVersion: opencloud.eu/v1
kind: KeycloakUser
metadata:
  name: admin
spec:
  username: admin
  email: admin@example.com
  passwordSecretRef:
    name: admin-credentials
    key: password
  roles:
    - opencloudAdmin
  groups:
    - /users

Implementation Details

1. Passwords: Always reference Kubernetes secrets, never hardcode
2. Realm Import: Extend the existing realm import to include users
3. Updates: Support updating users after initial deployment
4. Validation: Validate user definitions before applying

The implementation could use Keycloak's Admin API or realm import functionality, similar to how opencloud-compose handles it but with Kubernetes-native secret management.

Benefits

• GitOps Compatible: Users defined as code
• Secure: Passwords in Kubernetes secrets
• Auditable: User changes tracked in git
• Repeatable: Same users across environments
• Cloud-Native: Follows Kubernetes patterns

Use Cases

1. Development: Quickly spin up environments with test users
2. CI/CD: Automated testing with predefined users
3. Production: Declarative user management with proper secrets

Related Issues

• PR Add support for existing secrets and replace plaintext values with secrets #63: Add support for existing secrets (established the pattern for using Kubernetes secrets)
• Feature Reqeust: Inject sensitive values as secret #51: Inject sensitive values as secret (addressed by PR Add support for existing secrets and replace plaintext values with secrets #63)
• Standardize internal/external structure across all services #64: Standardize internal/external structure (would affect how users are configured)
• This complements the autoprovisioning configuration issue

Security Considerations

• Passwords must be stored in Kubernetes secrets
• Initial passwords should be marked for mandatory change
• Consider integration with external secret managers (Vault, etc.)
• Support for OIDC/SAML federation for production users