Write a documentation to set up keycloak integration with OpenProject via docker TLS

docker/dev/keycloak/.gitignore

@@ -0,0 +1 @@
+docker-compose.override.yml

docker/dev/keycloak/docker-compose.yml

@@ -0,0 +1,49 @@
+version: "3.9"
+
+services:
+  db-keycloak:
+    image: postgres:13
+    restart: always
+    networks:
+      - external
+    environment:
+      - POSTGRES_DB=keycloak
+      - POSTGRES_USER=keycloak
+      - POSTGRES_PASSWORD=keycloak
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:21.1
+    command: ["start-dev", "--proxy edge", "--spi-connections-http-client-default-disable-trust-manager=true"]
+    restart: no
+    networks:
+      - external
+    extra_hosts:
+      - "openproject.local:host-gateway"
+    environment:
+      - KC_DB_URL_HOST=db
+      - KC_DB_USERNAME=keycloak
+      - KC_DB_PASSWORD=keycloak
+      - KC_DB_URL_DATABASE=jdbc:postgresql://db:5432/keycloak
+      - KEYCLOAK_ADMIN=admin
+      - KEYCLOAK_ADMIN_PASSWORD=admin
+      - KC_DB_SCHEMA=public
+      - KC_HOSTNAME=keycloak.local
+    volumes:
+      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
+      - keycloak-data:/opt/keycloak/data/
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.keycloak-sub-secure.rule=Host(`keycloak.local`)"
+      - "traefik.http.routers.keycloak-sub-secure.entrypoints=websecure"
+      - "traefik.http.routers.keycloak-sub-secure.tls=true"
+      - "traefik.http.routers.keycloak-sub-secure.tls.certresolver=step"
+    depends_on:
+      - db-keycloak
+
+volumes:
+  keycloak-data:
+
+networks:
+  external:
+    name: gateway
+    external: true

docker/dev/tls/docker-compose.core-override.example.yml

@@ -2,10 +2,20 @@ services:
   backend:
     # The backend container needs some variables to be configured properly
     environment:
-      OPENPROJECT_CLI_PROXY: '${OPENPROJECT_DEV_URL}'
-      OPENPROJECT_DEV_EXTRA_HOSTS: '${OPENPROJECT_DEV_HOST}'
+      OPENPROJECT_CLI_PROXY: "${OPENPROJECT_DEV_URL}"
+      OPENPROJECT_DEV_EXTRA_HOSTS: "${OPENPROJECT_DEV_HOST}"
       OPENPROJECT_HTTPS: true
       SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt
+      # uncomment and set all the envs below to integrate keycloak with OpenProject
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_DISPLAY__NAME: Keycloak
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_HOST: keycloak.local
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_IDENTIFIER: https://openproject.local
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_SECRET: <The client secret you copied from keycloak>
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_ISSUER: https://keycloak.local/realms/<REALM>
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_AUTHORIZATION__ENDPOINT: /realms/<REALM>/protocol/openid-connect/auth
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_TOKEN__ENDPOINT: /realms/<REALM>/protocol/openid-connect/token
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_USERINFO__ENDPOINT: /realms/<REALM>/protocol/openid-connect/userinfo
+      # OPENPROJECT_OPENID__CONNECT_KEYCLOAK_END__SESSION__ENDPOINT: https://keycloak.local/realms/<REALM>/protocol/openid-connect/logout
     networks:
       - external
     volumes:

docker/dev/tls/docker-compose.override.example.yml

@@ -10,3 +10,4 @@ services:
           - openproject.local
           - nextcloud.local
           - gitlab.local
+          - keycloak.local

docs/development/development-environment-docker/README.md

@@ -420,6 +420,41 @@ Should you need to reset your root password, execute the following command:
 docker compose --project-directory docker/dev/gitlab exec -it gitlab gitlab-rake "gitlab:password:reset[root]"
 ```
 
+## Keycloak Service
+
+> NOTE: OpenID connect is an enterprise feature in OpenProject. So, to be able to use this feature for development setup, we need to have an `Enterprise Edition Token` which is restricted to the domain `openproject.local`
+
+Within `docker/dev/keycloak` a compose file is provided for running local keycloak instance with TLS support. This provides
+a production like environment for testing the OpenProject Keycloak integration against a keycloak instance accessible on `https://keycloak.local`.
+
+> NOTE: Configure [TLS Support](#tls-support) first before starting the Keycloak service
+
+### Running the Keycloak Instance
+
+Start up the docker compose service for Keycloak as follows:
+
+```shell
+docker compose --project-directory docker/dev/keycloak up -d
+```
+
+Once the keycloak service is started and running, you can access the keycloak instance on `https://keycloak.local` 
+and login with initial username and password as `admin`.
+
+Keycloak being an OpenID connect provider, we need to setup an OIDC integration for OpenProject.
+[Setup OIDC (keycloak) integration for OpenProject](https://www.openproject.org/docs/installation-and-operations/misc/custom-openid-connect-providers/#keycloak)
+
+Once the above setup is completed, In the root `docker-compose.override.yml` file, uncomment all the environment in `backend` service for keycloak and set the values according to configuration done in keycloak for OpenProject Integration.
+
+```shell
+# Stop all the service if already running
+docker compose down
+
+# or else simply start frontend service
+docker compose up -d frontend
+```
+
+Upon setting up all the things correctly, we can see a login with `keycloak` option in login page of `OpenProject`.
+
 ## Local files
 
 Running the docker images will change some of your local files in the mounted code directory. The