Skip to content
Star Fork

Managed Resources

This section covers how keycloak-config-cli manages and tracks resources in Keycloak realms.

Overview

keycloak-config-cli can operate in different management modes, determining how existing resources are handled during imports and updates.

Management Modes

Full Management Mode

When import.managed=true (default behavior):

  • Create: New resources are created
  • Update: Existing resources are updated to match configuration
  • Delete: Resources not present in import files are removed
  • Synchronize: Complete alignment between configuration and realm state

Partial Management Mode

When import.managed=partial:

  • Create: Only new resources are created
  • Update: Existing resources are left unchanged
  • Delete: No resources are removed
  • Preserve: Existing configurations are maintained

Resource Types

Users

{
  "users": [
    {
      "username": "john.doe",
      "email": "john.doe@example.com",
      "enabled": true,
      "attributes": {
        "department": "engineering"
      }
    }
  ]
}

Groups

{
  "groups": [
    {
      "name": "Developers",
      "path": "/developers",
      "attributes": {
        "description": "Development team group"
      }
    }
  ]
}

Roles

{
  "roles": [
    {
      "name": "app-user",
      "description": "Application user role",
      "composite": false,
      "clientRole": true
    }
  ]
}

Clients

{
  "clients": [
    {
      "clientId": "my-app",
      "name": "My Application",
      "enabled": true,
      "clientAuthenticatorType": "client-secret",
      "secret": "app-secret",
      "redirectUris": ["http://localhost:3000/*"],
      "webOrigins": ["http://localhost:3000"]
    }
  ]
}

Realms

{
  "realm": "my-realm",
  "enabled": true,
  "displayName": "My Realm",
  "loginTheme": "keycloak",
  "accountTheme": "keycloak"
}

Organizations

{
  "organizations": [
    {
      "name": "Acme Corp",
      "alias": "acme-corp",
      "enabled": true,
      "domains": ["acme.com"]
    }
  ]
}

Management Strategies

Create-Only Strategy

java -jar keycloak-config-cli.jar \
  --import.managed=create-only \
  --import.files=new-resources.json

Update-Only Strategy

java -jar keycloak-config-cli.jar \
  --import.managed=update-only \
  --import.files=updates.json

Delete-Only Strategy

java -jar keycloak-config-cli.jar \
  --import.managed=delete-only \
  --import.files=cleanup.json

Conflict Resolution

Automatic Conflict Detection

keycloak-config-cli automatically detects conflicts between:

  • Existing resources vs Import configuration
  • Schema changes vs Existing data
  • Dependency conflicts between related resources

Resolution Options

Strategy Description Use Case
SKIP Skip conflicting resources Development environments
OVERWRITE Replace existing resources Force updates
MERGE Combine configurations Preserving existing data 
java -jar keycloak-config-cli.jar \
  --import.conflict-strategy=MERGE \
  --import.conflict.prefer=import

State Tracking

State File Format

{
  "version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "realm": "my-realm",
  "resources": {
    "users": {
      "created": 5,
      "updated": 2,
      "deleted": 0
    },
    "groups": {
      "created": 3,
      "updated": 1,
      "deleted": 0
    }
  }
}

State Management Commands

# Enable state tracking
java -jar keycloak-config-cli.jar \
  --import.state.enabled=true \
  --import.state.file=state.json

# Show current state
java -jar keycloak-config-cli.jar \
  --import.state.show=true \
  --import.state.file=state.json

# Reset state
java -jar keycloak-config-cli.jar \
  --import.state.reset=true \
  --import.state.file=state.json

Selective Management

Resource Filtering

java -jar keycloak-config-cli.jar \
  --import.filter.type=users \
  --import.filter.attribute=department=engineering \
  --import.files=engineering-users.json

Exclusion Patterns

java -jar keycloak-config-cli.jar \
  --import.exclude.type=clients \
  --import.exclude.pattern=test-.* \
  --import.files=production-config.json

Best Practices

Resource Management

  1. Use Version Control: Keep configuration files in git
  2. Test in Staging: Validate changes before production
  3. Backup Data: Create realm backups before major changes
  4. Document Changes: Maintain changelog of resource modifications
  5. Use State Tracking: Enable state management for critical realms

Conflict Prevention

  1. Unique Naming: Use consistent naming conventions
  2. Dependency Planning: Understand resource relationships
  3. Incremental Changes: Make small, manageable updates
  4. Validation: Use built-in validation features
  5. Monitoring: Track resource creation and updates

Subgroup Management

By default, the subgroups of a group are managed globally. If a parent group is defined in the import configuration, any of its subgroups present in Keycloak but missing from that configuration will be deleted.

Setting import.managed.sub-group=no-delete allows managing subgroups across multiple configuration files. This is useful when you want to define subgroups for a container group across separate files without them deleting each other on import.

For example, you can have a federation that is retrieving groups from an LDAP directory. Some of those groups must be updated to provide specific roles. For readability, you want the groups from LDAP to be subgroups of a global container group (LDAPSync). For maintenance purposes, you prefer to have one configuration file per LDAP group.

Advanced Features

Custom Resource Types

{
  "customResources": [
    {
      "type": "custom-entity",
      "endpoint": "/api/custom",
      "management": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      }
    }
  ]
}

Batch Operations

java -jar keycloak-config-cli.jar \
  --import.batch.size=100 \
  --import.batch.delay=1000 \
  --import.parallel.enabled=true

Transaction Management

java -jar keycloak-config-cli.jar \
  --import.transaction.enabled=true \
  --import.transaction.timeout=30000