From 0d46a9391cb1fb5f4f5d6b88b2fdd3de1475ba91 Mon Sep 17 00:00:00 2001 From: Motouom Victoire Date: Mon, 2 Dec 2024 12:25:23 +0100 Subject: [PATCH 1/2] documentation for minimal export --- ...ting-a-minimal-import-json-after-export.md | 67 ++++++++ docs/config/remote-state-management.md | 147 ++++++++++++++++++ mkdocs.yml | 75 +++++++++ 3 files changed, 289 insertions(+) create mode 100644 docs/config/geting-a-minimal-import-json-after-export.md create mode 100644 docs/config/remote-state-management.md create mode 100644 mkdocs.yml diff --git a/docs/config/geting-a-minimal-import-json-after-export.md b/docs/config/geting-a-minimal-import-json-after-export.md new file mode 100644 index 000000000..c4852c193 --- /dev/null +++ b/docs/config/geting-a-minimal-import-json-after-export.md @@ -0,0 +1,67 @@ +# Getting Minimal Import After Realm Export + +This script is designed to clean up a Keycloak realm configuration file (in JSON format) by removing unnecessary fields, including all `id` fields, from the configuration. It is useful for simplifying the export of Keycloak realm data, especially when certain details like IDs are not needed for sharing or backup purposes. + +## Features + +- **Removes unnecessary default fields** such as `accessTokenLifespan`, `offlineSessionIdleTimeout`, and others that are typically not needed for a reimport. +- **Simplifies the realm configuration** while retaining all necessary data for further processing or importing into another Keycloak instance. + +## Requirements + +- **jq**: This script requires `jq`, a command-line JSON processor, to manipulate the JSON data. + + You can install `jq` using the following commands: + + - On Ubuntu/Debian: + ```bash + sudo apt-get install jq + ``` + - On macOS (with Homebrew): + ```bash + brew install jq + ``` + +## Usage + +Ensure you have the Keycloak realm configuration file (in JSON format) that you want to clean. The file should be named `realm-config.json` or you can modify the script to use your desired file path. + +### Download or Copy the Script + +```bash +#!/bin/bash + +INPUT_FILE="realm-config.json" +OUTPUT_FILE="keycloak-realm-export-minimal.json" + +jq 'del( + .id, .containerId, .accessTokenLifespanForImplicitFlow, + .accessTokenLifespanForWebApps, .accessTokenLifespan, .offlineSessionIdleTimeout, + .accessTokenLifespanInSeconds, .ssoSessionIdleTimeout, .ssoSessionMaxLifespan, + .ssoSessionIdleTimeoutRememberMe, .ssoSessionMaxLifespanRememberMe, + .accessCodeLifespan, .accessCodeLifespanLogin, .accessCodeLifespanUserAction, + .accessCodeLifespanMobile, .notBefore, .registrationAllowed, + .registrationEmailAsUsername, .rememberMe, .verifyEmail, .resetPasswordFlow, + .editUsernameAllowed, .bruteForceProtected, .permanentLockout, .maxFailureWaitSeconds, + .minimumQuickLoginWaitSeconds, .waitIncrementSeconds, .quickLoginCheckMilliSeconds, + .maxDeltaTimeSeconds, .failureFactor, .requiredCredentials, .otpPolicyType, + .otpPolicyAlgorithm, .otpPolicyInitialCounter, .otpPolicyDigits, .otpPolicyLookAheadWindow, + .otpPolicyPeriod, .otpSupportedApplications, .webAuthnPolicyRpEntityName, + .webAuthnPolicyAttestationConveyancePreference, .webAuthnPolicyAuthenticatorAttachment, + .webAuthnPolicyRequireResidentKey, .webAuthnPolicyUserVerificationRequirement, + .webAuthnPolicyCreateTimeout, .webAuthnPolicyAssertionTimeout, + .webAuthnPolicyRegistrationRecoveryEnabled, .webAuthnPolicyRegistrationRecoveryCodesQuantity, + .webAuthnPolicyRegistrationTokenBindingRequired, .webAuthnPolicyRegistrationAttestationConveyancePreference, + .webAuthnPolicyRegistrationAuthenticatorSelectionCriteria, .keys +) +| walk(if type == "object" then del(.id) else . end)' < "$INPUT_FILE" > "$OUTPUT_FILE" + +echo "Minimal export saved to $OUTPUT_FILE" +``` + +### make the script executable +```bash + chmod +x clean-realm-config.sh +``` + +Now execute the script, making sure that you have inputed the correct file paths. \ No newline at end of file diff --git a/docs/config/remote-state-management.md b/docs/config/remote-state-management.md new file mode 100644 index 000000000..9f8510900 --- /dev/null +++ b/docs/config/remote-state-management.md @@ -0,0 +1,147 @@ +## Remote State Management + +Remote state management ensures that configurations are tracked and only modified when necessary, enabling safe and controlled updates to Keycloak configurations without altering unmanaged resources. + +Ensure your project directory has the following structure for sample demonstration locally: + +```plaintext +keycloak-setup/ +├── docker-compose.yml +├── import.sh +├── keycloak-config-cli.jar +└── realms/ +└── state-management.json +``` + +Each file serves the following purpose: + +- `docker-compose.yml`: Defines the Keycloak service. +- `import.sh`: Custom shell script for running the Keycloak Config CLI against our Keycloak instance. +- `keycloak-config-cli.jar`: Keycloak-config-cli is compatible with different versions of Keycloak and actively maintained. +- `realms/state-management.json`: JSON file with realm configuration. + + +In `docker-compose.yml`, configure the Keycloak service without a Keycloak Config CLI container, as we will be handling imports manually in this case. + +```yaml +services: + keycloak: + image: quay.io/keycloak/keycloak:25.0.1 + environment: + KEYCLOAK_ADMIN: admin + KEYCLOAK_ADMIN_PASSWORD: admin + KC_HOSTNAME: localhost + KC_HTTP_PORT: "8080" + KC_HTTP_ENABLED: "true" + KC_METRICS_ENABLED: "true" + KC_HEALTH_ENABLED: "true" + ports: + - "8080:8080" + volumes: + - ./realms:/opt/keycloak/data/import:z + command: + - "start-dev" +``` + +This file configures Keycloak with essential parameters and maps `./realms` for importing configuration files. + + +The `import.sh` script uses the `keycloak-config-cli.jar` to apply configurations. This script will: + +1. Copy the config file to the container. +2. Run the import using the CLI JAR file, with remote state management enabled. + + +Create `import.sh` as follows: + +```bash +#!/bin/bash + +# Check if a configuration file is provided +if [ -z "$1" ]; then + echo "Usage: ./import.sh " + exit 1 +fi + +CONFIG_FILE=$1 + +# Run the Keycloak Config CLI tool with the updated options +java -jar keycloak-config-cli.jar \ + --keycloak.url="http://localhost:8080" \ + --keycloak.user="admin" \ + --keycloak.password="admin" \ + --import.managed.group="full" \ + --import.remote-state.enabled="true" \ + --import.files.locations="$CONFIG_FILE" + +echo "Import of $CONFIG_FILE with remote-state enabled is complete." +``` + + +Create `state-management.json` under `realms/`, which defines a Keycloak realm, clients, and roles. + + +Define the realm, clients, roles, and scope mappings for demonstration: + +```json +{ + "realm": "master", + "enabled": true, + "clients": [ + { + "clientId": "imported-client", + "enabled": true, + "protocol": "openid-connect", + "fullScopeAllowed": false + } + ], + "roles": { + "realm": [ + { + "name": "my-role", + "description": "A test role" + } + ] + }, + "clientScopes": [ + { + "name": "custom-scope", + "description": "Custom client scope", + "protocol": "openid-connect", + "attributes": { + "include.in.token.scope": "true" + } + } + ], + "scopeMappings": [ + { + "client": "imported-client", + "roles": [ + "my-role" + ] + } + ] +} +``` + +### Verifying Remote State Management + +With remote state management enabled, Keycloak Config CLI will only modify resources it initially created, preserving custom or manually added configurations. + +#### Starting Keycloak + +To start Keycloak, run: + +```shell +docker-compose up -d +``` + +#### Testing Remote State + +Manually create a dedicated client to test remote state management. + +#### Conclusion + +In this guide, we covered the basics of setting up Keycloak with Docker, creating an import script for configuration, and enabling remote state management using `keycloak-config-cli`. + +Feel free to reach out if you have any questions or need further assistance! \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..e68a26685 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,75 @@ +site_name: kc-config-cli +site_url: https://adorsys.github.io/keycloak-config-cli/ +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - navigation.top + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + language: en + palette: + - scheme: default + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + primary: teal + accent: purple + - scheme: slate + toggle: + icon: material/toggle-switch + name: Switch to light mode + primary: teal + accent: lime + +plugins: + - social + - search + +extra: + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/adorsys + - icon: fontawesome/brands/twitter + link: https://twitter.com/adorsys + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/in/adorsys/ + +nav: + - Home: + - Getting Started: index.md + - Supported Features: supported-features.md + - Import settings: import-settings.md + - managed-resources: managed-resource.md + - Redhat-sso compatibility: RedHat-SSO-compatibility.md + - Helm Chart: helm-chart.md + - Use Cases: + - Remote State Management: config/remote-state-management.md + - Adding Multiple post.logout.redirect.uris: config/addind-multiple-post-logout-redirect-uris.md + - Getting minimal import after realm export: config/geting-a-minimal-import-json-after-export.md + + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - admonition + - pymdownx.arithmatex: + generic: true + - footnotes + - pymdownx.details + - pymdownx.superfences + - pymdownx.mark + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +copyright: | + © 2024 Adorsys GmbH & Co. KG From 47efbd1f61778ad6dd8b39efc58bcc6538a010e3 Mon Sep 17 00:00:00 2001 From: Motouom Victoire Date: Mon, 2 Dec 2024 12:31:53 +0100 Subject: [PATCH 2/2] edit changelog for minimal config PR --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc428e0a2..15b81bdd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ### Added - improved logging for realm retrieval errors [#1010](https://github.com/adorsys/keycloak-config-cli/issues/1010) + +### Added +- Add documentation for minimal configuration [#1195](https://github.com/orgs/adorsys/projects/5/views/1?pane=issue&itemId=80856237&issue=adorsys%7Ckeycloak-config-cli%7C933) ### Fixed - Fix required action import handling for no-delete option [#834](https://github.com/adorsys/keycloak-config-cli/issues/834)