From 2193372f7dcad1eb9363274e28eb3e52c3d13eeb Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Tue, 16 Jun 2026 16:09:10 +0200 Subject: [PATCH 1/2] 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. From eb7db46188648567a1b60d0de9ac3db5ec575244 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Tue, 30 Jun 2026 16:49:58 +0200 Subject: [PATCH 2/2] reworked the webfinger part --- .../external-idp.md | 5 +- .../keycloak.md | 16 +- docs/admin/getting-started/kubernetes.md | 7 - .../admin/getting-started/kubernetes.md | 7 - .../external-idp.md | 173 +++++++++--------- .../keycloak.md | 91 +++++---- .../admin/getting-started/kubernetes.md | 7 - 7 files changed, 157 insertions(+), 149 deletions(-) delete mode 100644 docs/admin/getting-started/kubernetes.md delete mode 100644 versioned_docs/version-4.0/admin/getting-started/kubernetes.md delete mode 100644 versioned_docs/version-7.2/admin/getting-started/kubernetes.md 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 6863da9ed..a8771a110 100644 --- a/docs/admin/configuration/authentication-and-user-management/external-idp.md +++ b/docs/admin/configuration/authentication-and-user-management/external-idp.md @@ -82,8 +82,9 @@ 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. +the different OpenCloud clients. They already ship with the following +defaults, so you only need to set them if your IDP requires different client +IDs or scopes: ```env WEBFINGER_WEB_OIDC_CLIENT_ID=web diff --git a/docs/admin/configuration/authentication-and-user-management/keycloak.md b/docs/admin/configuration/authentication-and-user-management/keycloak.md index 0d3322e68..a5af10081 100644 --- a/docs/admin/configuration/authentication-and-user-management/keycloak.md +++ b/docs/admin/configuration/authentication-and-user-management/keycloak.md @@ -27,6 +27,14 @@ are documented in the [generic external IDP guide](./external-idp.md). ### Client Configuration +If you use the official `opencloud-compose` Docker Compose setup with Keycloak +(see [Shared User Directory Mode](#shared-user-directory-mode) below), the +required OIDC clients are already pre-configured in Keycloak through the +`keycloak-realm.dist.json` import and match the client IDs and scopes +OpenCloud expects by default. You only need to configure the clients manually +if you are not using this Docker Compose setup or run a custom Keycloak +deployment. + Use the client IDs and scopes from the [generic external IDP guide](./external-idp.md) when creating the Keycloak clients. @@ -36,7 +44,9 @@ Create one public OpenID Connect client in Keycloak for each OpenCloud client type that should connect to this deployment: Web, Android, iOS, and Desktop. The client IDs configured in Keycloak must match the client IDs configured in -OpenCloud through WebFinger: +OpenCloud through WebFinger. OpenCloud already ships with the following +defaults, so you only need to set the corresponding environment variables if +you want to use different client IDs: ```env WEBFINGER_WEB_OIDC_CLIENT_ID=web @@ -52,7 +62,9 @@ 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: +usable by the clients. These are already the OpenCloud defaults, so you only +need to set the corresponding environment variables if you want to use +different scopes: ```env WEBFINGER_WEB_OIDC_CLIENT_SCOPES=openid profile email diff --git a/docs/admin/getting-started/kubernetes.md b/docs/admin/getting-started/kubernetes.md deleted file mode 100644 index 27b5b0209..000000000 --- a/docs/admin/getting-started/kubernetes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 8 -id: kubernetes -title: Kubernetes -description: Kubernetes -draft: true ---- diff --git a/versioned_docs/version-4.0/admin/getting-started/kubernetes.md b/versioned_docs/version-4.0/admin/getting-started/kubernetes.md deleted file mode 100644 index 27b5b0209..000000000 --- a/versioned_docs/version-4.0/admin/getting-started/kubernetes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 8 -id: kubernetes -title: Kubernetes -description: Kubernetes -draft: true ---- diff --git a/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/external-idp.md b/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/external-idp.md index b167652b6..a8771a110 100644 --- a/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/external-idp.md +++ b/versioned_docs/version-7.2/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,101 @@ 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. They already ship with the following +defaults, so you only need to set them if your IDP requires different client +IDs or scopes: + +```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 +186,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/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/keycloak.md b/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/keycloak.md index a56b2ebcb..a5af10081 100644 --- a/versioned_docs/version-7.2/admin/configuration/authentication-and-user-management/keycloak.md +++ b/versioned_docs/version-7.2/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,70 @@ 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 + +If you use the official `opencloud-compose` Docker Compose setup with Keycloak +(see [Shared User Directory Mode](#shared-user-directory-mode) below), the +required OIDC clients are already pre-configured in Keycloak through the +`keycloak-realm.dist.json` import and match the client IDs and scopes +OpenCloud expects by default. You only need to configure the clients manually +if you are not using this Docker Compose setup or run a custom Keycloak +deployment. + +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. OpenCloud already ships with the following +defaults, so you only need to set the corresponding environment variables if +you want to use different client IDs: ```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. These are already the OpenCloud defaults, so you only +need to set the corresponding environment variables if you want to use +different scopes: -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 +335,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. diff --git a/versioned_docs/version-7.2/admin/getting-started/kubernetes.md b/versioned_docs/version-7.2/admin/getting-started/kubernetes.md deleted file mode 100644 index 27b5b0209..000000000 --- a/versioned_docs/version-7.2/admin/getting-started/kubernetes.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 8 -id: kubernetes -title: Kubernetes -description: Kubernetes -draft: true ----