{ "info": { "author": "Applause Team", "author_email": "eng@applause.com", "bugtrack_url": null, "classifiers": [ "Programming Language :: Python :: 3 :: Only", "Topic :: System :: Shells", "Topic :: Utilities" ], "description": "# Keycloak Configuration Tool\n\nThe purpose of this tool is to allow for configuration-based updates to the Keycloak service. The tool will:\n\n* Process the actions configuration\n* Decrypt any string values encrypted with the [kms-encryption-toolbox](https://github.com/ApplauseOSS/kms-encryption-toolbox)\n* Wait for Keycloak to become available\n* Execute the configured actions against Keycloak\n\n## Local Installation\n\nThis tool requires that `python3` and `pip3` be installed on your machine for a local installation. Once those tools are installed, simply run the following command to install the tool:\n```\npip3 install .\n```\n\nThis will create an executable named `keycloak-config-tool` in your path.\n\n## Running tests\n\nYou need tox in order to run tests. If you don't have it, you can execute \n```\npip3 install tox\n``` \n\nThen you can run tests just by calling\n```\ntox\n```\nfrom the root repository folder.\n\n## Command-line Usage\n\nThe tool takes the following command-line flags:\n\n| Name | Required? | Default | Description | Example |\n|:----------------------|:---------:|:----------:|:-------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------|\n| `--keycloak-base-url` | Yes | ***NONE*** | The base URL for Keycloak. | `--keycloak-base-url https://keycloak.host/auth/` |\n| `--keycloak-timeout` | No | 180 | The timeout (in seconds) to use when waiting for keycloak to become available. | `--keycloak-timeout 300` |\n| `--keycloak-username` | Yes | ***NONE*** | The username of an admin user on the Keycloak instance. | `--keycloak-username admin` |\n| `--keycloak-password` | Yes | ***NONE*** | The password for the admin user. | `--keycloak-password password` |\n| `--deploy-config-dir` | Yes | ***NONE*** | The path to the root directory. The tool will expect to find the `src` and `var` directories under this directory. | `--deploy-config-dir ./deploy` |\n| `--deploy-env` | Yes | ***NONE*** | The deployment environment (use 'local' for local stacks). | `--deploy-env local` |\n| `--config-only` | No | ***NONE*** | If provided, only print out the configuration, and take no further action. | `--config-only` |\n| `--encryption-prefix` | No | decrypt: | Prefix of all encrypted values to be used to determine if any decryption is required. | `--encryption-prefix _DECRYPT_:` |\n| `--aws-profile` | No | ***NONE*** | AWS profile to be used for contacting KMS when decryption is required. | `--aws-profile saml` |\n\n## Docker Usage\n\nThe tool is also available as a Docker image for use in `docker-compose` environments. The image repository is located at:\n\n```\napplause/keycloak-config-tool\n```\n\nThe image takes the following environment variables:\n\n| Name | Required? | Default | Description | Example |\n|:-------------------------|:---------:|:----------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------|\n| `KEYCLOAK_BASE_URL` | Yes | ***NONE*** | The base URL for Keycloak. | `KEYCLOAK_BASE_URL=https://keycloak.host/auth/` |\n| `KEYCLOAK_TIMEOUT` | No | 180 | The timeout (in seconds) to use when waiting for keycloak to become available. | `KEYCLOAK_TIMEOUT=300` |\n| `KEYCLOAK_USERNAME` | Yes | ***NONE*** | The username of an admin user on the Keycloak instance. | `KEYCLOAK_USERNAME=admin` |\n| `KEYCLOAK_PASSWORD` | Yes | ***NONE*** | The password for the admin user. | `KEYCLOAK_PASSWORD=password` |\n| `DEPLOY_CONFIG_DIR` | Yes | ***NONE*** | The path to the root directory. The tool will expect to find the `src` and `var` directories under this directory. This directory will need to be a accessible as a mounted volume. | `DEPLOY_CONFIG_DIR=/mnt/deploy` |\n| `DEPLOY_ENV` | Yes | ***NONE*** | The deployment environment (use 'local' for local stacks). | `DEPLOY_ENV=local` |\n| `COMPLETION_SIGNAL_PORT` | No | ***NONE*** | For dockerize compatibility. A port to open up a TCP listener on when the tool completes successfully. This will allow integration test docker-compose environments to know when the tool has successfully completed. If no value is provided, the container will simply stop when it completes. | `COMPLETION_SIGNAL_PORT=3456` |\n| `ENCRYPTION_PREFIX` | No | decrypt: | Prefix of all encrypted values to be used to determine if any decryption is required. | `ENCRYPTION_PREFIX=_DECRYPT_:` |\n| `AWS_PROFILE` | No | ***NONE*** | AWS profile to be used for contacting KMS when decryption is required. | `AWS_PROFILE=saml` |\n\n## Configuration\n\nThe tool expects a specific configuration file structure under the directory specified by `--deploy-config-dir`:\n```\n.\n+-- src\n| +-- keycloak.json \n+-- var\n +-- keycloak\n +-- *.var\n```\n\nThe `keycloak.json` file is contains a JSON array of action configurations (covered later). The var files support a variables file for each environment (e.g., `local.var`) plus a `defaults.var` file. The order of precedence for variables is:\n\n1. Environment variables\n2. Variables located in the environment-specific variables file\n3. Variables located in the `defaults.var` variables file\n\nVariables are substituted in the `keycloak.json` file using a `#{VAR}` syntax, **NOT a `${VAR}` syntax, as Keycloak API JSON payloads already support that syntax.**\n\n### Actions\n\nEach action supports the following properties:\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------|\n| `name` | Yes | ***NONE*** | The name of the action. This name must be unique. | `\"name\": \"importTestRealm\"` |\n| `action` | Yes | ***NONE*** | The type of the action (covered later). | `\"action\": \"importRealm\"` |\n| `description` | No | ***NONE*** | The description for the action. | `\"description\": \"Create a test user for integration testing.\"` |\n| `ignore` | No | false | If `true`, then the action will be ignored. Otherwise, the action will be executed. Defaults to false. Parameterizing this property allows for certain actions to be executed for certain environments. | `\"ignore\": #{IGNORE_IMPORT_TEST_REALM}` |\n\n\n### Supported Actions\n\nThe following actions are supported by the tool.\n\n#### importRealm\n\nImports a realm into Keycloak via a realm file. **This action can only be run in the `local` environment**.\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:------------------------------------------------------------------------------------------------------|:--------------------------------------------|\n| `realmFile` | Yes | ***NONE*** | The file containing the realm to be imported. This file's path is relative to the configuration file. | `\"realmFile\": \"./keycloak/test-realm.json\"` |\n| `overwrite` | No | false | Whether or not to overwrite the realm if it already exists. | `\"overwrite\": true` |\n\n#### createRole\n\nCreates a role in Keycloak.\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:------------------------------------------------------------------------------------------------------------------|:----------------------|\n| `realmName` | Yes | ***NONE*** | The name of the realm. | `\"realmName\": \"test\"` |\n| `role` | Yes | ***NONE*** | [The Keycloak role representation.](http://www.keycloak.org/docs-api/3.0/rest-api/index.html#_rolerepresentation) | `\"role\": { ... }` |\n\n#### createClient\n\nCreates a client in Keycloak. ***NOTE:*** The client secret MUST be a lower-cased UUID.\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:----------------------------------------------------------------------------------------------------------------------|:---------------------------|\n| `realmName` | Yes | ***NONE*** | The name of the realm. | `\"realmName\": \"test\"` |\n| `roles` | No | [] | The roles to apply to the client service account. | `\"roles\": [ \"test-role\" ]` |\n| `client` | Yes | ***NONE*** | [The Keycloak client representation.](http://www.keycloak.org/docs-api/3.0/rest-api/index.html#_clientrepresentation) | `\"client\": { ... }` |\n\n#### createUser\n\nCreates a user in Keycloak. ***NOTE:*** The `username` field is not needed. This field will be auto-populated from the `email` field.\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:------------------------------------------------------------------------------------------------------------------|:---------------------------|\n| `realmName` | Yes | ***NONE*** | The name of the realm. | `\"realmName\": \"test\"` |\n| `roles` | No | [] | The roles to apply to the user. | `\"roles\": [ \"test-role\" ]` |\n| `password` | No | ***NONE*** | The password to apply to the user. | `\"password\": \"test123\"` |\n| `user` | Yes | ***NONE*** | [The Keycloak user representation.](http://www.keycloak.org/docs-api/3.0/rest-api/index.html#_userrepresentation) | `\"user\": { ... }` |\n\n#### custom\n\nRun a custom action. The custom action file must contain a class named `CustomAction`. See [test/data/deploy/src/keycloak/test_custom.py](test/data/deploy/src/keycloak/test_custom.py) for an example.\n\n| Property Name | Required? | Default | Description | Example |\n|:--------------|:---------:|:----------:|:-----------------------------------------------------------------------------------------------------|:-------------------------------------------|\n| `file` | Yes | ***NONE*** | The file containing the custom action class. This file's path is relative to the configuration file. | `\"realmFile\": \"./keycloak/test_custom.py\"` |", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "keycloak", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "keycloak-config-tool", "package_url": "https://pypi.org/project/keycloak-config-tool/", "platform": "", "project_url": "https://pypi.org/project/keycloak-config-tool/", "project_urls": null, "release_url": "https://pypi.org/project/keycloak-config-tool/0.0.6/", "requires_dist": null, "requires_python": "", "summary": "This package allows for configuration based updates to Keycloak.", "version": "0.0.6" }, "last_serial": 5458249, "releases": { "0.0.6": [ { "comment_text": "", "digests": { "md5": "2fb6e1eff869f1564765bc0a4a284078", "sha256": "69bdb0d84bf4d25bbedbcd6c3c9fb5203337f99c2f71bf95fa6cde0699b39c12" }, "downloads": -1, "filename": "keycloak-config-tool-0.0.6.tar.gz", "has_sig": false, "md5_digest": "2fb6e1eff869f1564765bc0a4a284078", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15402, "upload_time": "2019-06-27T18:30:44", "url": "https://files.pythonhosted.org/packages/dc/21/b2711350ec3593b6a9bdda46525c3bcc70ede382e2f7e6a2a575722c58c9/keycloak-config-tool-0.0.6.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "2fb6e1eff869f1564765bc0a4a284078", "sha256": "69bdb0d84bf4d25bbedbcd6c3c9fb5203337f99c2f71bf95fa6cde0699b39c12" }, "downloads": -1, "filename": "keycloak-config-tool-0.0.6.tar.gz", "has_sig": false, "md5_digest": "2fb6e1eff869f1564765bc0a4a284078", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15402, "upload_time": "2019-06-27T18:30:44", "url": "https://files.pythonhosted.org/packages/dc/21/b2711350ec3593b6a9bdda46525c3bcc70ede382e2f7e6a2a575722c58c9/keycloak-config-tool-0.0.6.tar.gz" } ] }