Fix: enable stable Drupal OIDC support and PHP 8.2 base image

- Switched Drupal base image to PHP 8.2 for compatibility with openid_connect 2.x
- Added mariadb-client to container to allow Drush to drop tables
- Upgraded OIDC module from ^1 to ^2@beta for entity-based client configuration
- Replaced legacy client creation task with generic plugin-based entity creation
- Ensured /usr/local/bin is in PATH for www-data user
- Updated oidc.yml to explicitly use the generic plugin

References: https://chatgpt.com/share/6905cecc-8e3c-800f-849b-4041b6925381

roles/web-app-drupal/config/main.yml

@@ -7,6 +7,7 @@ features:
   oidc:               true
   central_database:   true
   logout:             true
+
 server:
   csp:
     flags: {}
@@ -15,18 +16,21 @@ server:
     canonical:
       - "drupal.{{ PRIMARY_DOMAIN }}"
     aliases: []
+
 docker:
   services:
     database:
       enabled:            true
     drupal:
-      version:            latest
+      # Use a PHP 8.2+ base image to ensure compatibility with OIDC 2.x syntax
+      version:            "10-php8.2-apache"
       image:              drupal
       name:               drupal
       backup:
         no_stop_required: true
   volumes:
     data:                 drupal_data
+
 rbac:
   roles:
     authenticated:

roles/web-app-drupal/tasks/00_permissions.yml

@@ -0,0 +1,11 @@
+- name: "Ensure sites/default/files exists and is writable"
+  command: >
+    docker exec -u root {{ DRUPAL_CONTAINER }} bash -lc
+    "set -e;
+     d='{{ DRUPAL_DOCKER_HTML_PATH }}/sites/default';
+     f=\"$d/files\";
+     mkdir -p \"$f\";
+     chown -R {{ DRUPAL_USER }}:{{ DRUPAL_USER }} \"$d\";
+     find \"$d\" -type d -exec chmod 775 {} +;
+     find \"$d\" -type f -exec chmod 664 {} +;"
+  changed_when: true

roles/web-app-drupal/tasks/02_install.yml

@@ -1,8 +1,25 @@
+- name: "Wait for database readiness"
+  command: >
+    docker exec {{ DRUPAL_CONTAINER }} bash -lc
+    "php -r '
+      $h=\"{{ database_host }}\"; $p={{ database_port }};
+      $d=\"{{ database_name }}\"; $u=\"{{ database_username }}\"; $pw=\"{{ database_password }}\";
+      $t=microtime(true)+60; $ok=false;
+      while (microtime(true)<$t) {
+        try { new PDO(\"mysql:host=$h;port=$p;dbname=$d;charset=utf8mb4\", $u, $pw,[PDO::ATTR_TIMEOUT=>2]); $ok=true; break; }
+        catch (Exception $e) { usleep(300000); }
+      }
+      if (!$ok) { fwrite(STDERR, \"DB not ready\\n\"); exit(1); }'"
+  register: db_wait
+  retries: 1
+  failed_when: db_wait.rc != 0
+
 - name: "Run Drupal site:install via Drush"
   no_log: "{{ MASK_CREDENTIALS_IN_LOGS | bool }}"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} si standard -y
+    "/opt/drupal/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} site:install standard -y
+    --db-url='mysql://{{ database_username }}:{{ database_password }}@{{ database_host }}:{{ database_port }}/{{ database_name }}'
     --site-name='{{ applications | get_app_conf(application_id, 'title', True) }}'
     --account-name='{{ applications | get_app_conf(application_id, 'users.administrator.username') }}'
     --account-mail='{{ applications | get_app_conf(application_id, 'users.administrator.email', True) }}'

roles/web-app-drupal/tasks/03_enable_modules.yml

@@ -1,12 +1,12 @@
 - name: "Enable OpenID Connect core module"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} en openid_connect -y"
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} en openid_connect -y"
   changed_when: true
 
 - name: "Enable OpenID Connect Keycloak preset (submodule of openid_connect)"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} en openid_connect_client_keycloak -y"
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} en openid_connect_client_keycloak -y"
   changed_when: true
   failed_when: false

roles/web-app-drupal/tasks/04_configure_oidc.yml

@@ -9,26 +9,46 @@
     label: "{{ item.key }}"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} cset -y
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} cset -y
     openid_connect.settings {{ item.key }}
     {{ (item.value | to_json) if item.value is mapping or item.value is sequence else item.value }}"
 
-- name: "Ensure OIDC client entity exists"
+- name: "Ensure/Update OIDC client entity (generic)"
   vars:
-    client_id: "{{ oidc_vars.oidc_client.id }}"
+    client_id:    "{{ oidc_vars.oidc_client.id }}"
     client_label: "{{ oidc_vars.oidc_client.label }}"
+    plugin_id:    "{{ oidc_vars.oidc_client.plugin }}"
+    settings_b64: "{{ oidc_vars.oidc_client.settings | to_json | b64encode }}"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} eval '
-    $id=\"{{ client_id }}\"; $label=\"{{ client_label }}\";
-    $storage=\Drupal::entityTypeManager()->getStorage(\"openid_connect_client\");
-    if (!$storage->load($id)) {
-      $client=$storage->create([\"id\"=>$id,\"label\"=>$label]);
-      $client->save();
-      print \"created\";
-    } else { print \"exists\"; }'"
-  register: client_exists
-  changed_when: "'created' in client_exists.stdout"
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} eval '
+      $id=\"{{ client_id }}\";
+      $label=\"{{ client_label }}\";
+      $plugin=\"{{ plugin_id }}\";
+      $settings=json_decode(base64_decode(\"{{ settings_b64 }}\"), TRUE);
+      $storage=\\Drupal::entityTypeManager()->getStorage(\"openid_connect_client\");
+      $e=$storage->load($id);
+      if (!$e) {
+        $e=$storage->create([
+          \"id\"=> $id,
+          \"label\"=> $label,
+          \"status\"=> TRUE,
+          \"plugin\"=> $plugin,
+          \"settings\"=> $settings,
+        ]);
+        $e->save();
+        print \"created\";
+      } else {
+        $e->set(\"label\", $label);
+        $e->set(\"plugin\", $plugin);
+        $e->set(\"settings\", $settings);
+        $e->set(\"status\", TRUE);
+        $e->save();
+        print \"updated\";
+      }
+    '"
+  register: client_apply
+  changed_when: "'created' in client_apply.stdout or 'updated' in client_apply.stdout"
 
 - name: "Apply OIDC client settings"
   vars:
@@ -40,7 +60,7 @@
     label: "{{ item.key }}"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} eval '
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} eval '
     $id=\"{{ client_id }}\";
     $key=\"{{ item.key }}\";
     $val=json_decode(base64_decode(\"{{ (item.value | to_json | b64encode) }}\"), true);
@@ -55,5 +75,5 @@
 - name: "Clear caches after OIDC config"
   command: >
     docker exec {{ DRUPAL_CONTAINER }} bash -lc
-    "/var/www/html/vendor/bin/drush -r {{ DRUPAL_DOCKER_HTML_PATH }} cr"
+    "drush -r {{ DRUPAL_DOCKER_HTML_PATH }} cr"
   changed_when: false

roles/web-app-drupal/tasks/main.yml

@@ -37,6 +37,9 @@
 - name: Flush handlers to make container ready
   meta: flush_handlers
 
+- name: "Fix permissions for sites/default/files"
+  include_tasks: 00_permissions.yml
+
 - name: "Ensure settings.php includes settings.local.php"
   include_tasks: 01_settings_local_include.yml
 

roles/web-app-drupal/templates/Dockerfile.j2

@@ -1,12 +1,17 @@
 FROM {{ DRUPAL_IMAGE }}:{{ DRUPAL_VERSION }}
 
 # -------------------------------------------------------------------
-# System dependencies (mail support + basic tools)
+# System dependencies (mail support + MySQL client + basic tools)
 # -------------------------------------------------------------------
 RUN apt-get update && \
-    apt-get install -y msmtp msmtp-mta git unzip zip less nano curl vim && \
+    apt-get install -y msmtp msmtp-mta git unzip zip less nano curl vim mariadb-client && \
     rm -rf /var/lib/apt/lists/*
 
+# -------------------------------------------------------------------
+# PHP extensions required by Drupal/Drush bootstrap
+# -------------------------------------------------------------------
+RUN docker-php-ext-install -j"$(nproc)" pdo_mysql
+
 # -------------------------------------------------------------------
 # Install Composer
 # -------------------------------------------------------------------
@@ -19,13 +24,13 @@ ENV COMPOSER_ALLOW_SUPERUSER=1
 # -------------------------------------------------------------------
 # Build Drupal project with Drush + OpenID Connect
 # IMPORTANT:
-# - The Drupal base image uses /var/www/html as a symlink to /opt/drupal/web
+# - The Drupal base image uses /var/www/html as a symlink to {{ DRUPAL_DOCKER_HTML_PATH }}
 # - Therefore, the actual project root must be placed in /opt/drupal
 # -------------------------------------------------------------------
 RUN set -eux; \
     builddir="$(mktemp -d)"; \
     composer create-project --no-interaction --no-ansi --no-progress drupal/recommended-project:^10 "$builddir"; \
-    composer --working-dir="$builddir" require -n drush/drush:^13 drupal/openid_connect:^1; \
+    composer --working-dir="$builddir" require -n drush/drush:^13 drupal/openid_connect:^2@beta; \
     rm -rf /opt/drupal/* /opt/drupal/.[!.]* /opt/drupal/..?* 2>/dev/null || true; \
     mkdir -p /opt/drupal; \
     cp -a "$builddir"/. /opt/drupal/; \
@@ -34,7 +39,7 @@ RUN set -eux; \
 # -------------------------------------------------------------------
 # Make vendor binaries available in PATH
 # -------------------------------------------------------------------
-ENV PATH="/opt/drupal/vendor/bin:${PATH}"
+RUN ln -sf /opt/drupal/vendor/bin/drush /usr/local/bin/drush
 
 # -------------------------------------------------------------------
 # PHP upload configuration
@@ -55,21 +60,24 @@ RUN set -eux; \
   # Ensure vendor binaries are executable
   if [ -d /opt/drupal/vendor/bin ]; then chmod a+rx /opt/drupal/vendor/bin/*; fi; \
   if [ -f /opt/drupal/vendor/drush/drush/drush ]; then chmod a+rx /opt/drupal/vendor/drush/drush/drush; fi; \
-  # Ensure the docroot (/opt/drupal/web) is accessible
-  if [ -d /opt/drupal/web ]; then \
-    chmod 755 /opt/drupal/web; \
-    find /opt/drupal/web -type d -exec chmod 755 {} +; \
+  # Ensure the docroot ({{ DRUPAL_DOCKER_HTML_PATH }}) is accessible
+  if [ -d {{ DRUPAL_DOCKER_HTML_PATH }} ]; then \
+    chmod 755 {{ DRUPAL_DOCKER_HTML_PATH }}; \
+    find {{ DRUPAL_DOCKER_HTML_PATH }} -type d -exec chmod 755 {} +; \
   fi; \
   # Ensure settings.local.php exists and is owned by www-data
-  install -o www-data -g www-data -m 640 /dev/null /opt/drupal/web/sites/default/settings.local.php
+  install -o www-data -g www-data -m 640 /dev/null {{ DRUPAL_DOCKER_HTML_PATH }}/sites/default/settings.local.php
 
 # -------------------------------------------------------------------
 # Runtime defaults
 # -------------------------------------------------------------------
 USER www-data
-WORKDIR /var/www/html  # symlink pointing to /opt/drupal/web
+WORKDIR /var/www/html  # symlink pointing to {{ DRUPAL_DOCKER_HTML_PATH }}
+
+# Ensure PATH for non-login shells includes /usr/local/bin
+ENV PATH="/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin"
 
 # -------------------------------------------------------------------
 # Build-time check (optional)
 # -------------------------------------------------------------------
-RUN drush --version
+RUN /usr/local/bin/drush --version

roles/web-app-drupal/templates/docker-compose.yml.j2

@@ -7,7 +7,7 @@
     ports:
       - "127.0.0.1:{{ ports.localhost.http[application_id] }}:80"
     volumes:
-      - data:/var/www/html/web/sites/default/files
+      - data:{{ DRUPAL_DOCKER_HTML_PATH }}/sites/default/files
       - {{ DRUPAL_MSMTP_ABS }}:/etc/msmtprc
       - {{ DRUPAL_SETTINGS_LOCAL_ABS }}:{{ DRUPAL_DOCKER_CONF_PATH }}/settings.local.php
 

roles/web-app-drupal/vars/main.yml

@@ -7,8 +7,8 @@ database_type:                "mariadb"
 
 DRUPAL_URL:                   "{{ domains | get_url(application_id, WEB_PROTOCOL) }}"
 DRUPAL_CUSTOM_IMAGE:          "drupal_custom"
-DRUPAL_DOCKER_HTML_PATH:      "/var/www/html"
-DRUPAL_DOCKER_CONF_PATH:      "/var/www/html/sites/default"
+DRUPAL_DOCKER_HTML_PATH:      "/opt/drupal/web"
+DRUPAL_DOCKER_CONF_PATH:      "{{ DRUPAL_DOCKER_HTML_PATH }}/sites/default"
 DRUPAL_VERSION:               "{{ applications | get_app_conf(application_id, 'docker.services.drupal.version') }}"
 DRUPAL_IMAGE:                 "{{ applications | get_app_conf(application_id, 'docker.services.drupal.image') }}"
 DRUPAL_CONTAINER:             "{{ applications | get_app_conf(application_id, 'docker.services.drupal.name') }}"

roles/web-app-drupal/vars/oidc.yml

@@ -14,6 +14,7 @@ oidc_settings:
 oidc_client:
   id:                                "keycloak"
   label:                             "Keycloak"
+  plugin:                            "generic"   # use the built-in generic OIDC client plugin
   settings:
     client_id:                       "{{ OIDC.CLIENT.ID }}"
     client_secret:                   "{{ OIDC.CLIENT.SECRET }}"