From 04993020588c6d801e87866090a3ece9f1237c28 Mon Sep 17 00:00:00 2001
From: Dominik Schmidt <dev@dominik-schmidt.de>
Date: Thu, 31 Jul 2025 19:56:38 +0200
Subject: [PATCH] docs: explain how to bootstrap an admin user with authelia
 (currently)

---
 idm/external-authelia.yml | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/idm/external-authelia.yml b/idm/external-authelia.yml
index e4f5322..bc42d07 100644
--- a/idm/external-authelia.yml
+++ b/idm/external-authelia.yml
@@ -6,9 +6,31 @@ services:
       PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD: "none"
       PROXY_OIDC_SKIP_VERIFICATION: "false"
 
-      # oidc assignment driver currently doesn't work with the desktop client: https://github.com/opencloud-eu/desktop/issues/217
-      PROXY_ROLE_ASSIGNMENT_DRIVER: "default"
-      GRAPH_ASSIGN_DEFAULT_USER_ROLE: "true"
+      # Enable authelia usernames as username in OpenCloud (instead of an id)
+      # PROXY_USER_OIDC_CLAIM: "preferred_username"
+      # PROXY_AUTOPROVISION_CLAIM_USERNAME: "preferred_username"
 
       PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM: "groups"
       WEB_OIDC_SCOPE: "openid profile email groups"
+
+      # The desktop client currently doesn't work when oidc assignment driver is used : https://github.com/opencloud-eu/desktop/issues/217
+      # That's why you only can use it to bootstrap your admin user currently (if you want to use the desktop client).
+      #
+      # 1. *Before* first startup: Switch to `PROXY_ROLE_ASSIGNMENT_DRIVER: "oidc"`
+      # 2. Start opencloud container to generate initial config: `docker compose up -d`
+      # 3. Map the `opencloud-admin` group from authelia to the `admin` role from OpenCloud in opencloud-config/opencloud.yaml :
+      #
+      # proxy:
+      #   role_assignment:
+      #    oidc_role_mapper:
+      #        role_claim: groups
+      #        role_mapping:
+      #          - role_name: admin
+      #            claim_value: opencloud-admin
+      #
+      # 4. Restart opencloud container: `docker compose restart opencloud`
+      # 5. Login with your admin user (the one with the `opencloud-admin` group)
+      # 6. Switch back to `PROXY_ROLE_ASSIGNMENT_DRIVER: "default"``
+      # 7. Recreate opencloud container: `docker compose up -d opencloud`
+      PROXY_ROLE_ASSIGNMENT_DRIVER: "default"
+      GRAPH_ASSIGN_DEFAULT_USER_ROLE: "true"