From 7f614d3ce8624b7e1772ceffdfb0d4059012bc0a Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Tue, 16 Jun 2026 16:09:10 +0200 Subject: [PATCH] rework the external-idp and keycloak docs --- .../external-idp.md | 172 +++++++++--------- .../keycloak.md | 79 ++++---- 2 files changed, 127 insertions(+), 124 deletions(-) diff --git a/docs/admin/configuration/authentication-and-user-management/external-idp.md b/docs/admin/configuration/authentication-and-user-management/external-idp.md index b167652b6..6863da9ed 100644 --- a/docs/admin/configuration/authentication-and-user-management/external-idp.md +++ b/docs/admin/configuration/authentication-and-user-management/external-idp.md @@ -10,11 +10,9 @@ draft: false ## Requirements -OpenCloud is able to integrate with external OpenID Connect Identity Providers -(IDP). However the implementation is currently somewhat opinionated and has -certain requirements on the IDP. The project is working on loosening some -of the requirements in order to allow OpenCloud to work with a broader range of -identity providers. +OpenCloud integrates with external OpenID Connect Identity Providers (IDPs). +The setup is opinionated, but the requirements below are provider-independent. +For a provider-specific example, see [Keycloak integration](./keycloak.md). This is the list of minimal requirements that an IDP needs to fulfill in order to work with OpenCloud: @@ -25,55 +23,100 @@ to work with OpenCloud: authorization code flow with PKCE. Therefore the IDP needs to support this flow. - All clients, except the Web client, use predefined client IDs. Therefore the IDP needs to be able to create clients with predefined IDs. -- All clients, except the Web client, use a hardcoded list of scopes they request from the IDP. - As certain features of OpenCloud (especially the automatic role assignment) rely on specific claims - being present in the access token or the UserInfo response, the IDP needs to be able to provide - additional claims in the Tokens even if the client does not explicitly request them via scopes. +- OpenCloud provides client IDs and scopes for the Web, Desktop, Android, and iOS + apps through the OpenCloud WebFinger service. Configure these values in the + OpenCloud deployment so that clients can discover the correct OIDC settings. +- The IDP must return the claims required by OpenCloud in the access token or + through the UserInfo endpoint. Configure scopes and claim mappings in the IDP + accordingly. ## OpenCloud Configuration The following environment variables are relevant when connecting OpenCloud to -an external IDP. An example configuration for Keycloak is provided the -[Keycloak integration](./keycloak.md) documentation. +an external IDP. -- `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider -- `OC_EXCLUDE_RUN_SERVICES`: When using and external IDP the built-in Identity Provider - does not need to run. So add `idp` here to prevent the internal `idp` service from - starting. +### Configure the OIDC issuer + +```env +IDP_DOMAIN=idp.example.org +IDP_ISSUER_URL=https://idp.example.org/realms/openCloud +OC_OIDC_ISSUER=https://idp.example.org/realms/openCloud +``` + +Do not include the protocol in `IDP_DOMAIN`. Use `idp.example.org`, not +`https://idp.example.org`. + +- `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider. +- `OC_EXCLUDE_RUN_SERVICES`: When using an external IDP, the built-in Identity + Provider does not need to run. Add `idp` here to prevent the internal `idp` + service from starting. +- `PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD`: Set this to `jwt` so OpenCloud + verifies access tokens as JWTs using the Identity Provider's published + signing keys. - `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity Provider's `.well-known/openid-configuration` endpoint via the OpenCloud base - urls. This helps the oidc clients, that do not yet support discovery via - webfinger to locate the Identity Provider's configuration. + URLs. - `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables - configure how the users mapped between the Identity Provider and OpenCloud. + configure how users are mapped between the Identity Provider and OpenCloud. `PROXY_USER_OIDC_CLAIM` defines the OIDC claim that OpenCloud uses to uniquely identify a user. It is matched against the OpenCloud user attribute - defined in `PROXY_USER_CS3_CLAIM`. E.g. if `PROXY_USER_OIDC_CLAIM` is set to - `preferred_username` and `PROXY_USER_CS3_CLAIM` is set to `username` then an - OpenID Connect user, that has the `preferred_username` set to `alan` will map + defined in `PROXY_USER_CS3_CLAIM`. For example, if `PROXY_USER_OIDC_CLAIM` + is set to `preferred_username` and `PROXY_USER_CS3_CLAIM` is set to + `username`, then an OpenID Connect user with `preferred_username=alan` maps to the OpenCloud user with username `alan`. - `PROXY_AUTOPROVISION_ACCOUNTS` and `GRAPH_USERNAME_MATCH`: When - `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true`, OpenCloud will create a new - user account in the LDAP Database for every user who logs in via OpenID - Connect for the first time. Enabling this requires access to a writable LDAP - server. For smaller setups this can be the built-in LDAP server provided by - the `idm` service. If set to `false` all users logging in must already be - existing in the LDAP server. (The mapping between the OIDC and LDAP users - happens based on the aforementioned `PROXY_USER_OIDC_CLAIM` and - `PROXY_USER_CS3_CLAIM` settings. Set `GRAPH_USERNAME_MATCH` to `none` when - `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true` to disable OpenCloud's - default restrictions on allowed characters in usernames. -- `PROXY_ROLE_ASSIGNMENT_DRIVER` and `GRAPH_ASSIGN_DEFAULT_USER_ROLE`: For - details see below + `PROXY_AUTOPROVISION_ACCOUNTS` is set to `true`, OpenCloud creates a new user + account in the LDAP database for every user who logs in via OpenID Connect + for the first time. This requires a writable LDAP server. For smaller setups, + the built-in LDAP server provided by the `idm` service can be used. If set to + `false`, users must already exist in LDAP. +- `PROXY_ROLE_ASSIGNMENT_DRIVER` and `GRAPH_ASSIGN_DEFAULT_USER_ROLE`: See the + section below. + +If you use Docker Compose with an external IDP, add `idm/external-idp.yml` to +`COMPOSE_FILE`. + +### Configure client discovery with WebFinger + +OpenCloud clients discover OIDC client settings through the OpenCloud WebFinger +service at `https:///.well-known/webfinger`. + +The WebFinger OIDC variables define which client ID and scopes are returned to +the different OpenCloud clients. Set them in your deployment configuration; the +values are required. + +```env +WEBFINGER_WEB_OIDC_CLIENT_ID=web +WEBFINGER_WEB_OIDC_CLIENT_SCOPES=openid profile email + +WEBFINGER_ANDROID_OIDC_CLIENT_ID=OpenCloudAndroid +WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES=openid profile email offline_access + +WEBFINGER_IOS_OIDC_CLIENT_ID=OpenCloudIOS +WEBFINGER_IOS_OIDC_CLIENT_SCOPES=openid profile email offline_access + +WEBFINGER_DESKTOP_OIDC_CLIENT_ID=OpenCloudDesktop +WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES=openid profile email offline_access +``` + +:::note + +- Android and iOS clients use the WebFinger discovery mechanism. +- The Desktop Client does not fully support this discovery mechanism yet. + Configure the Desktop Client WebFinger variables anyway so the setup is ready + for client support and stays consistent. + + ::: ### Automatic Role Assignments :::note -As the OpenCloud clients currently only request a hardcoded list of `scopes`, -the automatic role-assignment currently requires the IDP to be able to provide -additional claims in the Access Token and the UserInfo endpoint independent of -the requested `scopes`. If your IDP does not support this, automatic role -assignment will not work. +Automatic role assignment requires the IDP to provide the configured role claim +in the access token or through the UserInfo endpoint. Make sure that the +configured scopes and claim mappings return this claim for OpenCloud clients. + +If the IDP does not provide the required role claim, automatic role assignment +with the `oidc` driver will not work. ::: When users login into OpenCloud, they get a user role assigned @@ -142,56 +185,3 @@ The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The :::note When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` it is recommended to set `GRAPH_ASSIGN_DEFAULT_USER_ROLE` to `false`. ::: - -## Client Configuration - -OpenCloud requires several OIDC clients to be configured in the Identity Provider. - -### Web Client - -The web client is used for browser-based access to OpenCloud: - -- Client ID: `web` -- Client Type: Public client -- Redirect URIs: - - `https://your-domain.example.com/` - - `https://your-domain.example.com/oidc-callback.html` - - `https://your-domain.example.com/oidc-silent-redirect.html` -- Post Logout Redirect URIs: - - `https://your-domain.example.com/` - -### Desktop Client - -The desktop client is used for the OpenCloud desktop application: - -- Client ID: `OpenCloudDesktop` -- Client Type: Public client -- Redirect URIs: - - `http://127.0.0.1` - - `http://localhost` - -### Mobile App Clients - -#### Android App - -- Client ID: `OpenCloudAndroid` -- Client Type: Public client -- Redirect URIs: `oc://android.opencloud.eu` -- Post Logout Redirect URIs: `oc://android.opencloud.eu` - -#### iOS App - -- Client ID: `OpenCloudIOS` -- Client Type: Public client -- Redirect URIs: `oc://ios.opencloud.eu` -- Post Logout Redirect URIs: `oc://ios.opencloud.eu` - -### Additional Clients - -#### Cyberduck File Transfer Client - -- Client ID: `Cyberduck` -- Client Type: Public client -- Redirect URIs: - - `x-cyberduck-action:oauth` - - `x-mountainduck-action:oauth` diff --git a/docs/admin/configuration/authentication-and-user-management/keycloak.md b/docs/admin/configuration/authentication-and-user-management/keycloak.md index a56b2ebcb..0d3322e68 100644 --- a/docs/admin/configuration/authentication-and-user-management/keycloak.md +++ b/docs/admin/configuration/authentication-and-user-management/keycloak.md @@ -8,7 +8,9 @@ draft: false # Keycloak Integration -OpenCloud supports using Keycloak as an external identity provider, providing enterprise-grade identity management capabilities. This guide explains how to set up and configure Keycloak with OpenCloud. +OpenCloud supports using Keycloak as an external identity provider, providing enterprise-grade identity management capabilities. +For issuer variables, WebFinger client discovery, and Docker Compose requirements, see the [generic external IDP documentation](./external-idp.md). + This guide is divided into three main sections: - [Keycloak Integration Overview](#opencloud-configuration-for-keycloak-general): A brief overview of the integration process. @@ -17,48 +19,58 @@ This guide is divided into three main sections: ## OpenCloud Configuration for Keycloak (General) -When using Keycloak as the identity provider, you need to understand the general configuration settings if you want to configure your custom integration. +When using Keycloak as the identity provider, keep the Keycloak-specific parts of the setup here: +realm, clients, scopes, mappers, and logout behavior. + +The OpenCloud issuer, WebFinger discovery, and Docker Compose external IDP setup +are documented in the [generic external IDP guide](./external-idp.md). + +### Client Configuration + +Use the client IDs and scopes from the [generic external IDP guide](./external-idp.md) +when creating the Keycloak clients. + +### Manual Client Configuration -You can also use one of our predefined Docker Compose setups, which are located in the `opencloud-compose` repository. These setups include all necessary configurations for Keycloak and OpenLDAP. +Create one public OpenID Connect client in Keycloak for each OpenCloud client +type that should connect to this deployment: Web, Android, iOS, and Desktop. -### Server Configuration +The client IDs configured in Keycloak must match the client IDs configured in +OpenCloud through WebFinger: ```env -PROXY_AUTOPROVISION_ACCOUNTS=true|false # that depends on your setup -PROXY_ROLE_ASSIGNMENT_DRIVER=oidc -OC_OIDC_ISSUER=https://your-domain.example.com/realms/openCloud -WEB_OPTION_ACCOUNT_EDIT_LINK_HREF=https://your-domain.example.com/realms/openCloud/account -PROXY_OIDC_REWRITE_WELLKNOWN=true -PROXY_USER_OIDC_CLAIM=preferred_username|sub|uuid # this depends on your setup -# admin and demo accounts must be created in Keycloak -OC_ADMIN_USER_ID: "" -SETTINGS_SETUP_DEFAULT_ASSIGNMENTS: "false" -GRAPH_ASSIGN_DEFAULT_USER_ROLE: "false" -GRAPH_USERNAME_MATCH=none -OC_EXCLUDE_RUN_SERVICES=idp,idm # it is not supported to run keycloak with the built-in idm +WEBFINGER_WEB_OIDC_CLIENT_ID=web +WEBFINGER_ANDROID_OIDC_CLIENT_ID=OpenCloudAndroid +WEBFINGER_IOS_OIDC_CLIENT_ID=OpenCloudIOS +WEBFINGER_DESKTOP_OIDC_CLIENT_ID=OpenCloudDesktop ``` -Look [OpenCloud external IDP configuration](./external-idp#opencloud-configuration) for some more details about these settings. +Configure each client as a public OIDC client and enable the authorization code +flow with PKCE. Do not configure a client secret. -### Client Configuration +The scopes configured on the Keycloak clients must provide the claims required +by OpenCloud. Make sure the access token or UserInfo response contains the user, +email, profile, group, and role information required by your OpenCloud setup. +The WebFinger OIDC scopes configured in OpenCloud must exist in Keycloak and be +usable by the clients: -The [OIDC clients](./external-idp#client-configuration) required by OpenCloud are pre-configured in the Docker Compose setup and match the clients used by the built-in IdP. +```env +WEBFINGER_WEB_OIDC_CLIENT_SCOPES=openid profile email +WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES=openid profile email offline_access +WEBFINGER_IOS_OIDC_CLIENT_SCOPES=openid profile email offline_access +WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES=openid profile email offline_access +``` -### Manual Client Configuration +Configure the required redirect URIs for each client according to the OpenCloud +client configuration used by your deployment. -If you need to manually configure the clients in Keycloak: +Keycloak client scopes and mappers must provide the claims required for user +mapping, user provisioning if enabled, and role assignment when the `oidc` +driver is used. -1. Log in to the Keycloak admin console -2. Select the OpenCloud realm -3. Navigate to Clients and click Create -4. Configure each client according to the specifications above -5. Ensure all clients have the appropriate scopes: - - web-origins - - profile - - roles - - groups - - basic - - email +For the generic OpenCloud external IDP requirements, including issuer +variables, WebFinger client discovery, required claims, and Docker Compose +setup, see [External OpenID Connect Identity Provider](./external-idp.md). ### Advanced Configuration @@ -311,7 +323,8 @@ The Docker Compose file `idm/external-idp.yml` contains the complete configurati :::warning -Your external IdP configuration must match the settings described in the [Client Configuration](#client-configuration) section above. +Your external IdP configuration must match the client IDs and scopes described in the +[generic external IDP guide](./external-idp.md). Your external IdP must provide the required claims for user provisioning and role assignment.