Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve doc of managed resources #1188

Merged
merged 7 commits into from
Nov 29, 2024
Merged

Improve doc of managed resources #1188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8601a47
improve resource management documentation
Motouom Nov 8, 2024
fc1454c
update changelog
Motouom Nov 8, 2024
8eb6e10
Add state management in the documentaion.
Motouom Nov 13, 2024
5923432
removed unwanted changes
Motouom Nov 13, 2024
ab7e207
fix merge conflict.
Motouom Nov 14, 2024
c954cea
Update MANAGED.md
Motouom Nov 27, 2024
cf69020
Merge branch 'main' into improve-managed-resources
Motouom Nov 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
- otpPolicyAlgorithm ignored during import [#847](https://github.com/adorsys/keycloak-config-cli/issues/847)

### Added

- Added Navigation in the readme [#1187](https://github.com/adorsys/keycloak-config-cli/issues/1187)
### Added
- Improve documentation of managed resources, particularly user federations [#826](https://github.com/adorsys/keycloak-config-cli/issues/826)

- Added Navigation in the readme [#1099](https://github.com/adorsys/keycloak-config-cli/issues/1099)

### Added
- improved logging for realm retrieval errors [#1010](https://github.com/adorsys/keycloak-config-cli/issues/1010)
### Fixed
Expand Down
80 changes: 48 additions & 32 deletions docs/MANAGED.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,72 @@
# Full managed resources
## Resource Management
### Introduction

keycloak-config-cli manage some types of resources absolutely. For example if a `group` isn't defined
inside the import json but other `groups` specified, keycloak-config-cli will calculate the
difference and delete the `group` from keycloak.
This document explains how keycloak-config-cli (kc-cli) manages resources in Keycloak, including its default behavior, customization options, and impact on various resource types.

In some cases it is required to include some keycloak defaults because keycloak-config-cli can't
detect if the entity comes from a user or auto created by keycloak itself.
### How keycloak-config-cli Tracks Resources

There are 2 modes to ensure a specific behavior:
- keycloak-config-cli stores information about resources it creates as realm attributes in the Keycloak database.
- This tracking mechanism allows kc-cli to manage these resources in subsequent runs.

### 1. Keycloak should not manage type of resources:
### Default Behavior

For example if you don't define any `groups` inside the import json, keycloak does not touch any `groups`.
- By default, kc-cli will delete and recreate resources that it initially created in previous runs.
- This ensures that the Keycloak configuration always matches the state defined in your configuration files.

### 2. Keycloak manage type of resources:
### Customizing Resource Management

For example define any `groups` you want inside the import json, keycloak ensure that the groups are available but other
groups will be deleted. If you define `groups` but set an empty array, keycloak will delete all groups in keycloak.
- The `import.managed.*` family of properties allows you to customize this behavior.
- Setting these properties to `no-delete` will prevent kc-cli from deleting resources, even if they're no longer present in your configuration files.

## Supported full managed resources
### Impact on User Federations

- This behavior applies to user federations (such as LDAP and Active Directory).
- When a user federation is deleted and recreated, all users created by that federation will also be deleted.
- This includes associated data like offline tokens.

### Full Managed Resources

keycloak-config-cli manages some types of resources absolutely. For example, if a `group` isn't defined inside the import JSON but other `groups` are specified, keycloak-config-cli will calculate the difference and delete the `group` from Keycloak.

In some cases, it is required to include some Keycloak defaults because keycloak-config-cli can't detect if the entity comes from a user or is auto-created by Keycloak itself.

### Management Modes

1. **Keycloak Should Not Manage Type of Resources**:
- If you don't define any `groups` inside the import JSON, Keycloak does not touch any `groups`.

2. **Keycloak Manages Type of Resources**:
- If you define any `groups` you want inside the import JSON, Keycloak ensures that those groups are available but deletes other groups.
- If you define `groups` but set an empty array, Keycloak will delete all groups in Keycloak.

### Supported Full Managed Resources

| Type | Additional Information | Resource Name |
|---------------------------------|----------------------------------------------------------------------------------|----------------------------------|
| Groups | - | `group` |
| Required Actions | You have to copy the default one to you import json. | `required-action` |
| Required Actions | You have to copy the default one to your import JSON. | `required-action` |
| Client Scopes | - | `client-scope` |
| Scope Mappings | - | `scope-mapping` |
| Client Scope Mappings | - | `client-scope-mapping` |
| Roles | - | `role` |
| Components | You have to copy the default components to you import json. | `component` |
| Sub Components | You have to copy the default components to you import json. | `sub-component` |
| Authentication Flows | You have to copy the default components to you import json, expect builtin flows | `authentication-flow` |
| Components | You have to copy the default components to your import JSON. | `component` |
| Sub Components | You have to copy the default components to your import JSON. | `sub-component` |
| Authentication Flows | You have to copy the default components to your import JSON, except built-in flows.| `authentication-flow` |
| Identity Providers | - | `identity-provider` |
| Identity Provider Mappers | - | `identity-provider-mapper` |
| Clients | - | `client` |
| Clients Authorization Resources | The 'Default Resource' is always included. | `client-authorization-resources` |
| Clients Authorization Policies | - | `client-authorization-policies` |
| Clients Authorization Scopes | - | `client-authorization-scopes` |
| Message Bundles | Only message bundles imported with config-cli will be managed/deleted. | `message-bundles` |
| Clients Authorization Resources | The 'Default Resource' is always included. | `client-authorization-resources` |
| Clients Authorization Policies | - | `client-authorization-policies` |
| Clients Authorization Scopes | - | `client-authorization-scopes` |
| Message Bundles | Only message bundles imported with config-cli will be managed/deleted. | `message-bundles` |

## Disable deletion of managed entities
### Disabling Deletion of Managed Entities

If you don't delete properties of a specific type, you can disable this behavior by default a properties like `import.managed.<entity>=<full|no-delete>`, e.g.:
`import.managed.required-actions=no-delete`
If you don't want to delete properties of a specific type, you can disable this behavior by setting properties like `import.managed.<entity>=<full|no-delete>`, e.g.:

## State management
```properties
import.managed.required-actions=no-delete
```
### State management

If `import.remote-state.enabled` is set to `true` (default value), keycloak-config-cli will purge only resources they created before by keycloak-config-cli. If `import.remote-state.enabled` is set to `false`, keycloak-config-cli will purge all existing entities if they are not defined in import json.

Motouom marked this conversation as resolved.
Show resolved Hide resolved
### Supported resources

Following entities does have saved state:

- Required Actions
- Components
Loading