4sp1r3 / stuart-keycloak

Keycloak with JSON-based configuration utility.

Stuart Keycloak

Dockerized local instance of Keycloak with JSON-based configuration utility.

This project is owned by ✨DevEx Convoy✨. Feel free to use #convoy-developer-experience channel to reach us out.

Setup

Prerequisites:

• Docker 🐳
• Docker Compose
• For Mac M1 users, your own keycloak build (see bin/build_keycloak_image)

Copy files with env variables:

$ cp .env.sample .env
$ cp .client_secrets.env.sample .client_secrets.env

If you have already docker and docker-compose installed, you can start Keycloak with underlaying DB by executing: $ docker-compose up To make sure that services are up, visit Keycloak admin afterwards.

Using Keycloak Config CLI

Container with configuration tool won't run unless it's started explicitly with: docker-compose keycloak-config-cli This tool loads all the files from the ./keycloak_config directory, applies the changes to the Keycloak and shuts itself down. Of course, the container with Keycloak has to be up, and there is no need to restart it to see the changes.

⚠️ Instead of configuring Keycloak via its GUI, please use JSON files under ./keycloak_config. They are generated with:

$ bin/generate_migration -h
Usage: generate_migration [migration_name]
migration_name has to be snake_cased and can't contain digits or whitespaces.

# For example:
$ bin/generate_migation snake_cased_migration_name

⚠️ Be careful with the IMPORT_FORCE option. It's easy to unintentionally override the data while using JSON-formatted migrations.

Learn more about Keycloak Config CLI JSON file syntax from GitHub repository and check out examples.

Keeping secrets in secret

Keycloak does not allow exporting secrets, but you can import them. Secrets are stored in a migration file, but obviously, keeping them in plain text is reckless. We avoid it by using variable substitution.

If your migration contains client secret, please do the following:

1. Replace the "secret" in the migration file with the variable:

     {
       "enabled": true,
       "realm": "stuart",
       "clients": [
         {
           "clientId": "PlanEx",
           "name": "Planet Express Inc",
           "description": "Our crew is replaceable, your package isn't!",
           "enabled": true,
           "clientAuthenticatorType": "client-secret",
           "secret": "$(env:PLAN_EX_CLIENT_SECRET)", # Pick the right name for your variable
           "redirectUris": [
             "*"
           ],
           "webOrigins": [
             "*"
           ]
         }
       ],
       "attributes": {
         "custom": "test-step01"
       }
     }
   

2. Add your variable to the .client_secrets.env and .client_secrets.env.sample files. These will be used accordingly in your local env and as a sample for other developers.

   # .client_secrets.env
   ...
   PLAN_EX_CLIENT_SECRET="bite-my-shiny-metal-ass"
   
   

   # .client_secrets.env.sample
   ...
   PLAN_EX_CLIENT_SECRET="bite-my-shiny-metal-ass"
   

3. Run the migration, so you know that the substitution worked as expected. Using the Keycloak Admin Console>Clients tab, you can verify the result.
4. Add your variable to all the Consul environments under TBA directory. If it's a production environment, please put more effort into generating a complex and safe one. This step is critical because the deployment fails when the variable is not set. If you don't know how to do it, read: View and set runtime configuration for a Stuart project.

Deployment

TODO