Skip to content
Snippets Groups Projects
Select Git revision
  • master default
  • 1-mari
2 results

keycloak_integration.md

Blame
    • keycloak_integration.md 7.42 KiB

    Keycloak Integration

    This document contains the guidelines for integration of keycloak settings for the components.

    Table of contents

    Keycloak

    Keycloak is an open-source Identity and Access Management solution aimed at modern applications and services. We have it installed as a side service for the CaaS Framework. It is available at https://keycloak.emerald.tecnalia.com. For the integration of the components with Keycloak, we have defined two different realms: emerald-dev and emerald-prod. The emerald-dev realm is used for the development environment and the emerald-prod realm is used for the production environment.

    Approach

    Within Emerald we will use the adorsys/keycloak-config-cli:6.1.0-25.0.1 image to configure the Keycloak settings. This image is a CLI tool that allows you to manage the Keycloak settings using a configuration file. The configuration file is a JSON file that contains the settings for the Keycloak realms, clients, roles, etc.

    Each component in the CaaS Framework will have its own configuration files that will be used to configure the Keycloak settings. The configuration files should be stored in the component folder under a subfolder named configmaps/keycloak-setup-realm. The configuration files should be ordered by the order in which they should be applied in case there are dependencies between them.

    You can find an example of the configuration files in the rcm and amoe components.

    keycloak setup

    Getting the Keycloak settings

    The next doubt is how to get the Keycloak settings. There are two methods to get the Keycloak settings: Using the Keycloak admin console or exporting the settings via the keycloak cli within the container.

    The Keycloak admin console allows to partially export the settings. In the Realm Settings section, you can export the settings in the realm format. The realm format is a JSON file that contains the settings for the Keycloak realms, clients, roles, etc. .

    realm export

    This method has some limitations. The settings exported are not complete. For example, the settings for the users are not exported and the secrets are not exported. To get the complete settings, you can use the keycloak cli within the container.

    To get the complete settings you need to have access to the Keycloak container. For example, if you have initiate a local Keycloak container (using image keycloak/keycloak:25.0.1) named keycloak.

    export CONTAINER_ID=$(docker inspect keycloak | jq -r ".[0].Id")
export REALM=emerald-dev
docker exec -it  $CONTAINER_ID /bin/bash -c "kc.sh export --dir /tmp/export --realm $REALM"
docker cp $CONTAINER_ID:/tmp/export/. .

    this will bring us two files: emerald-dev-realm.json and emerald-dev-users-0.json. The first one contains the settings for the Keycloak realms, clients, roles, etc. The second one contains the settings for the users.

    To get the complete settings from the keycloak side service in the CaaS Framework, you will need the help of the CaaS Framework administrator. He will execute the following commands:

    kubectl config use-context emerald.openstack.rke2.admin
export REALM=emerald-dev
kubectl -n keycloak exec -it statefulset/keycloak -c keycloak -- /bin/bash -c "JAVA_OPTS_APPEND=\"-Djgroups.bind.port=8888 -Djgroups.dns.query=keycloak-http.keycloak.svc.cluster.local\" kc.sh export --dir /tmp/export --realm $REALM --db postgres --db-username \$KEYCLOAK_DATABASE_USER --db-password \$KEYCLOAK_DATABASE_PASSWORD --db-url \"jdbc:postgresql://\$KEYCLOAK_DATABASE_HOST/\$KEYCLOAK_DATABASE_NAME\" || true"
kubectl -n keycloak cp keycloak-0:/tmp/export/. .

    This will bring us the same two files: emerald-dev-realm.json and emerald-dev-users-0.json. From them the administrator will provide you the relevant sections for the concrete component.

    Add Keycloak configuration to the component

    Due to some issues with the component used to load the component keycloak configuration, and the request to be able to check the configuration separately, the keycloak configuration should be added to the component folder as a two subcomponents. One to contain the keycloak configuration and the other to contain loader for the keycloak configuration.

    keycloak configuration

    Kustomization

    The adorsys/keycloak-config-cli:6.1.0-25.0.1 supports variable substitution in the configuration files. The variables should be defined in the configuration file using the ${VARIABLE_NAME} format.

    For example if you want to setup the password of a user in the configuration file, you can define the password as ${USER_PASSWORD}. The adorsys/keycloak-config-cli:6.1.0-25.0.1 will replace the ${USER_PASSWORD} with the value of the USER_PASSWORD environment variable.

    {
  "realm": "emerald-dev",
  "users": [
    {
      "username" : "amoe_test",
      "firstName" : "amoe",
      "lastName" : "test",
      "email" : "amoe_test@not.exists",
      "emailVerified" : false,
      "enabled" : true,
      "totp" : false,
      "credentials" : [ {
        "type" : "password",
        "value" : "$(AMOE_PASSWORD)"
        } ],
      "disableableCredentialTypes" : [ ],
      "requiredActions" : [ ],
      "realmRoles" : [ "default-roles-emerald-dev", "AMOE_ADMIN" ],
      "notBefore" : 0,
      "groups" : [ ]
      }
  ]
}

    This will also require to add the AMOE_PASSWORD environment variable in the job configuration file amoe 01-realm-configuration-job.yaml.

    apiVersion: batch/v1
kind: Job
metadata:
  name: amoe-realm-configuration
  namespace: emerald-dev
spec:
  ttlSecondsAfterFinished: 20
  template:
    spec:
      containers:
      - name: amoe-realm-configuration
        image: adorsys/keycloak-config-cli:6.1.0-25.0.1
        env:
        - name: AMOE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: keycloak
              key: AMOE_PASSWORD

    and possibly to define the AMOE_PASSWORD in the ci/cd variables of the Gitlab project.

    Keycloak testing

    Besides in order to be able to test the keycloak configuration separately, the keycloak configuration should be added to keycloak overlay in the integration folder. We have two options to add the keycloak configuration to the keycloak overlay: Merged and splitted.

    Splitted

    The splitted test it only requires to add the keycloak components to the keycloak testing overlay. I.e. for rcm component we should add the following files:

    • ./../../../components/rcm/keycloak/data
    • ./../../../components/rcm/keycloak/loader

    Splitted

    Merged

    The merged test it requires to manually patch the keycloak config loader job. I.e. for rcm component we should add the following files:

    • ./../../../components/rcm/patches/keycloak-loader

    RCM Keycloak Patch

    Merged