adds keycloak guidelines

keycloak_integration.md

+# Keycloak Integration
+
+This document contains the guidelines for integration of keycloak settings for the components.
+
+## Table of contents
+- [Keycloak](#keycloak)
+- [Approach](#Approach)
+- [Getting the Keycloak settings](#getting-the-keycloak-settings)
+- [Kustomization](#kustomization)
+
+## 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](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.
+- https://git.code.tecnalia.com/emerald/private/devops/caas-framework/-/tree/master/rcm/configmaps/keycloak-setup-realm
+- https://git.code.tecnalia.com/emerald/private/devops/caas-framework/-/tree/master/amoe/configmaps/keycloak-setup-realm
+
+![keycloak setup](.media/image01.png)
+
+## 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. 
+.
+ - https://keycloak.emerald.digital.tecnalia.dev/admin/emerald-dev/console/#/emerald-dev/realm-settings
+
+![realm export](.media/image00.png)
+
+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`.
+
+```bash
+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:
+
+```bash
+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.
+
+## 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.
+
+```json
+{
+  "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`.
+
+```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.
+