Keycloak Configuration Tool

The purpose of this tool is to allow for configuration-based updates to the Keycloak service. The tool will:

Process the actions configuration
Decrypt any string values encrypted with the kms-encryption-toolbox
Wait for Keycloak to become available
Execute the configured actions against Keycloak

Local Installation

This 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:

pip3 install .

This will create an executable named keycloak-config-tool in your path.

Running tests

You need tox in order to run tests. If you don't have it, simply run the following to install it:

pip3 install tox

You can run tests just by calling in the repository root:

tox

Command-line Usage

The tool takes the following command-line flags:

Name	Required?	Default	Description	Example
`--keycloak-base-url`	Yes	NONE	The base URL for Keycloak.	`--keycloak-base-url https://keycloak.host/auth/`
`--keycloak-timeout`	No	180	The timeout (in seconds) to use when waiting for keycloak to become available.	`--keycloak-timeout 300`
`--keycloak-username`	Yes	NONE	The username of an admin user on the Keycloak instance.	`--keycloak-username admin`
`--keycloak-password`	Yes	NONE	The password for the admin user.	`--keycloak-password password`
`--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`
`--deploy-env`	Yes	NONE	The deployment environment (use 'local' for local stacks).	`--deploy-env local`
`--config-only`	No	NONE	If provided, only print out the configuration, and take no further action.	`--config-only`
`--encryption-prefix`	No	decrypt:	Prefix of all encrypted values to be used to determine if any decryption is required.	`--encryption-prefix _DECRYPT_:`
`--aws-profile`	No	NONE	AWS profile to be used for contacting KMS when decryption is required.	`--aws-profile saml`

Docker Usage

The tool is also available as a Docker image for use in docker-compose environments. The image repository is located at:

applause/keycloak-config-tool

The image takes the following environment variables:

Name	Required?	Default	Description	Example
`KEYCLOAK_BASE_URL`	Yes	NONE	The base URL for Keycloak.	`KEYCLOAK_BASE_URL=https://keycloak.host/auth/`
`KEYCLOAK_TIMEOUT`	No	180	The timeout (in seconds) to use when waiting for keycloak to become available.	`KEYCLOAK_TIMEOUT=300`
`KEYCLOAK_USERNAME`	Yes	NONE	The username of an admin user on the Keycloak instance.	`KEYCLOAK_USERNAME=admin`
`KEYCLOAK_PASSWORD`	Yes	NONE	The password for the admin user.	`KEYCLOAK_PASSWORD=password`
`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`
`DEPLOY_ENV`	Yes	NONE	The deployment environment (use 'local' for local stacks).	`DEPLOY_ENV=local`
`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`
`ENCRYPTION_PREFIX`	No	decrypt:	Prefix of all encrypted values to be used to determine if any decryption is required.	`ENCRYPTION_PREFIX=_DECRYPT_:`
`AWS_PROFILE`	No	NONE	AWS profile to be used for contacting KMS when decryption is required.	`AWS_PROFILE=saml`

Configuration

The tool expects a specific configuration file structure under the directory specified by --deploy-config-dir:

.
+-- src
|   +-- keycloak.json 
+-- var
    +-- keycloak
        +-- *.var

The 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:

Environment variables
Variables located in the environment-specific variables file
Variables located in the defaults.var variables file

Variables are substituted in the keycloak.json file using a #{VAR} syntax, NOT a ${VAR} syntax, as Keycloak API JSON payloads already support that syntax.

Actions

Each action supports the following properties:

Property Name	Required?	Default	Description	Example
`name`	Yes	NONE	The name of the action. This name must be unique.	`"name": "importTestRealm"`
`action`	Yes	NONE	The type of the action (covered later).	`"action": "importRealm"`
`description`	No	NONE	The description for the action.	`"description": "Create a test user for integration testing."`
`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}`

Supported Actions

The following actions are supported by the tool.

importRealm

Imports a realm into Keycloak via a realm file. This action can only be run in the local environment.

Property Name	Required?	Default	Description	Example
`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"`
`overwrite`	No	false	Whether or not to overwrite the realm if it already exists.	`"overwrite": true`

createRole

Creates a role in Keycloak.

Property Name	Required?	Default	Description	Example
`realmName`	Yes	NONE	The name of the realm.	`"realmName": "test"`
`role`	Yes	NONE	The Keycloak role representation.	`"role": { ... }`

createClient

Creates a client in Keycloak. NOTE: The client secret MUST be a lower-cased UUID.

Property Name	Required?	Default	Description	Example
`realmName`	Yes	NONE	The name of the realm.	`"realmName": "test"`
`roles`	No	[]	The roles to apply to the client service account.	`"roles": [ "test-role" ]`
`client`	Yes	NONE	The Keycloak client representation.	`"client": { ... }`

createUser

Creates a user in Keycloak. NOTE: The username field is not needed. This field will be auto-populated from the email field.

Property Name	Required?	Default	Description	Example
`realmName`	Yes	NONE	The name of the realm.	`"realmName": "test"`
`roles`	No	[]	The roles to apply to the user.	`"roles": [ "test-role" ]`
`password`	No	NONE	The password to apply to the user.	`"password": "test123"`
`user`	Yes	NONE	The Keycloak user representation.	`"user": { ... }`

custom

Run a custom action. The custom action file must contain a class named CustomAction. See test/data/deploy/src/keycloak/test_custom.py for an example.

Property Name	Required?	Default	Description	Example
`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"`

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

keycloak-config-tool-0.0.7.tar.gz (15.0 kB view details)

Uploaded Nov 16, 2020 Source

File details

Details for the file keycloak-config-tool-0.0.7.tar.gz.

File metadata

Download URL: keycloak-config-tool-0.0.7.tar.gz
Upload date: Nov 16, 2020
Size: 15.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/1.15.0 pkginfo/1.6.1 requests/2.25.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.52.0 CPython/3.5.10

File hashes

Hashes for keycloak-config-tool-0.0.7.tar.gz
Algorithm	Hash digest
SHA256	`9b1a901f4e8765e047fb0829e2b9f395aa8e25b428f0e85ab6091e4743ef5d3e`
MD5	`9e211d843324cd60c92a98a7e1d46406`
BLAKE2b-256	`9a358da15b365d9560913ad0a6d2859691d3a896fcf69f36e566b8dae88bedbb`

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.0.7 This release

Nov 16, 2020 1 file

0.0.6

Jun 27, 2019 1 file

keycloak-config-tool 0.0.7