From f81ce666eae8be686418cf56a739e00d000d5321 Mon Sep 17 00:00:00 2001 From: Ralf Haferkamp Date: Thu, 10 Apr 2025 17:24:02 +0200 Subject: [PATCH 1/3] Add some generic bits about integrating with external IDP This takes some bits from the keycloak page which are bascially relevant for integrating with any external IDP and puts them in a separate section. Also adds some bits about the claim based role assignment setup (taken from the proxy's service README). --- .../10-external-idp.md | 157 ++++++++++++++++++ .../30-keycloak.md | 67 +------- .../index.md | 17 ++ 3 files changed, 178 insertions(+), 63 deletions(-) create mode 100644 docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md rename docs/admin/30-configuration/{ => 30-authentication-and-user-management}/30-keycloak.md (65%) create mode 100644 docs/admin/30-configuration/30-authentication-and-user-management/index.md diff --git a/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md b/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md new file mode 100644 index 00000000..9dead922 --- /dev/null +++ b/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md @@ -0,0 +1,157 @@ +--- +sidebar_position: 1 +id: external-idp +title: External OpenID Connect Identity Provider +--- + +# Integrating external OpenID Connect Identity Providers + +## OpenCloud Configuration + +The following environment variables are relevant when connecting OpenCloud to an external IDP + +- `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider +- `OC_EXCLUDE_RUN_SERVICES`: To disable the builtin Identity Provider set this to `idp` +- `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity + Providers `.well-known/openid-configuration` via the OpenCloud base url. This + help the oidc client, that do not yet support discovery via webfinger to + locate the Identity Provider's configuration. +- `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables + configure now the users 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` and + OpenID Connect user, that has the `preferred_username` set to `alan` will map + 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 builtin 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 base 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 + +### Automatic Role Assignments + +When users login into OpenCloud, they do get a user role assigned +automatically. The automatic role assignment can be configured in different +ways. The `PROXY_ROLE_ASSIGNMENT_DRIVER` environment variable (or the `driver` +setting in the `role_assignment` section of the configuration file select which +mechanism to use for the automatic role assignment. + +When set to `default`, all users which do not have a role assigned at the time +for the first login will get the role 'user' assigned. (This is also the +default behavior if `PROXY_ROLE_ASSIGNMENT_DRIVER` is unset. + +When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a +user will happen based on the values of an OpenID Connect Claim of that user. +The name of the OpenID Connect Claim to be used for the role assignment can be +configured via the `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM` environment variable. It +is also possible to define a mapping of claim values to role names defined in +OpenCloud via a `yaml` configuration. See the following `proxy.yaml` snippet +for an example. + +```yaml +role_assignment: + driver: oidc + oidc_role_mapper: + role_claim: opencloudRoles + role_mapping: + - role_name: admin + claim_value: myAdminRole + - role_name: spaceadmin + claim_value: mySpaceAdminRole + - role_name: user + claim_value: myUserRole + - role_name: guest + claim_value: myGuestRole +``` + +This would assign the role `admin` to users with the value `myAdminRole` in the claim `opencloudRoles`. +The role `user` to users with the values `myUserRole` in the claims `opencloudRoles` and so on. + +Claim values that are not mapped to a specific OpenCloud role will be ignored. + +Note: An OpenCloud user can only have a single role assigned. If the configured +`role_mapping` and a user's claim values result in multiple possible roles for a user, the order in +which the role mappings are defined in the configuration is important. The first role in the +`role_mappings` where the `claim_value` matches a value from the user's roles claim will be assigned +to the user. So if e.g. a user's `opencloudRoles` claim has the values `myUserRole` and +`mySpaceAdminRole` that user will get the OpenCloud role `spaceadmin` assigned (because `spaceadmin` +appears before `user` in the above sample configuration). + +If a user's claim values don't match any of the configured role mappings an error will be logged and +the user will not be able to login. + +The default `role_claim` (or `PROXY_ROLE_ASSIGNMENT_OIDC_CLAIM`) is `roles`. The default `role_mapping` is: + +```yaml +- role_name: admin + claim_value: opencloudAdmin +- role_name: spaceadmin + claim_value: opencloudSpaceAdmin +- role_name: user + claim_value: opencloudUser +- role_name: guest + claim_value: opencloudGuest +``` + +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` + +### 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/30-configuration/30-keycloak.md b/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md similarity index 65% rename from docs/admin/30-configuration/30-keycloak.md rename to docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md index c8d49d66..fa6908eb 100644 --- a/docs/admin/30-configuration/30-keycloak.md +++ b/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md @@ -8,20 +8,6 @@ title: 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. -## Overview - -OpenCloud employs a dual-track authentication strategy: - -1. **Built-in IDP (Identity Provider)**: - - Based on LibreGraph Connect (lico) - - Targeted at smaller installations (up to 500 users) - - Designed for standalone or small deployments - -2. **External Identity Providers**: - - Keycloak as the recommended OIDC provider for larger installations - - Support for Azure AD, EntraID, ADFS through Keycloak - - Enterprise-focused solution - ## Setting Up Keycloak with Docker Compose OpenCloud includes a pre-configured Keycloak setup in the Docker Compose examples. To enable Keycloak: @@ -60,56 +46,11 @@ GRAPH_USERNAME_MATCH=none OC_EXCLUDE_RUN_SERVICES=idp ``` -## Client Configuration - -OpenCloud requires several OIDC clients to be configured in Keycloak. These clients are pre-configured in the Docker Compose setup and match the clients used by the built-in IdP: - -### 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` - -### Desktop Client +Look [here](./10-example-idp.md#opencloud-configuration) for some more details about these settings. -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 Configuration -- **Client ID**: `Cyberduck` -- **Client Type**: Public client -- **Redirect URIs**: - - `x-cyberduck-action:oauth` - - `x-mountainduck-action:oauth` +The [OIDC clients](./10-external-idp.md#client-configuration) required by OpenCloud are pre-configured in the Docker Compose setup and match the clients used by the built-in IdP. ## Advanced Configuration @@ -160,4 +101,4 @@ When Keycloak is enabled: 2. Groups are passed via OIDC tokens in the "groups" claim 3. OpenCloud maps external groups to internal representations -For more details on user management with Keycloak, refer to the [Keycloak documentation](https://www.keycloak.org/documentation). \ No newline at end of file +For more details on user management with Keycloak, refer to the [Keycloak documentation](https://www.keycloak.org/documentation). diff --git a/docs/admin/30-configuration/30-authentication-and-user-management/index.md b/docs/admin/30-configuration/30-authentication-and-user-management/index.md new file mode 100644 index 00000000..1499bc18 --- /dev/null +++ b/docs/admin/30-configuration/30-authentication-and-user-management/index.md @@ -0,0 +1,17 @@ +--- +title: 'Authentication and Identity Management' +--- + +# Authentication and Identity Management + +OpenCloud employs a dual-track authentication strategy: + +1. **Built-in IDP (Identity Provider)**: + - Based on LibreGraph Connect (lico) + - Targeted at smaller installations (up to 500 users) + - Designed for standalone or small deployments + +2. **External Identity Providers**: + - Keycloak as the recommended OIDC provider for larger installations + - Support for Azure AD, EntraID, ADFS through Keycloak + - Enterprise-focused solution From aab9a1f29364580b6937c27591b08e0b56f513aa Mon Sep 17 00:00:00 2001 From: Michael Barz Date: Mon, 14 Apr 2025 15:11:58 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Alex Co-authored-by: Phil Davis --- .../10-external-idp.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md b/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md index 9dead922..f2da024e 100644 --- a/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md +++ b/docs/admin/30-configuration/30-authentication-and-user-management/10-external-idp.md @@ -11,27 +11,27 @@ title: External OpenID Connect Identity Provider The following environment variables are relevant when connecting OpenCloud to an external IDP - `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider -- `OC_EXCLUDE_RUN_SERVICES`: To disable the builtin Identity Provider set this to `idp` +- `OC_EXCLUDE_RUN_SERVICES`: To disable the built-in Identity Provider set this to `idp` - `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity Providers `.well-known/openid-configuration` via the OpenCloud base url. This help the oidc client, that do not yet support discovery via webfinger to locate the Identity Provider's configuration. - `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables - configure now the users mapped between the Identity Provider and OpenCloud. + configure how the users 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` and + `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 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 builtin LDAP server provided by + 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 base on the aforementioned `PROXY_USER_OIDC_CLAIM` and + 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. @@ -40,14 +40,14 @@ The following environment variables are relevant when connecting OpenCloud to an ### Automatic Role Assignments -When users login into OpenCloud, they do get a user role assigned +When users login into OpenCloud, they get a user role assigned automatically. The automatic role assignment can be configured in different ways. The `PROXY_ROLE_ASSIGNMENT_DRIVER` environment variable (or the `driver` -setting in the `role_assignment` section of the configuration file select which +setting in the `role_assignment` section of the configuration file) select which mechanism to use for the automatic role assignment. When set to `default`, all users which do not have a role assigned at the time -for the first login will get the role 'user' assigned. (This is also the +of first login will get the role 'user' assigned. This is also the default behavior if `PROXY_ROLE_ASSIGNMENT_DRIVER` is unset. When `PROXY_ROLE_ASSIGNMENT_DRIVER` is set to `oidc` the role assignment for a From eba0776075684a2a65848633481c1c3726326e19 Mon Sep 17 00:00:00 2001 From: Michael Barz Date: Mon, 14 Apr 2025 16:15:03 +0200 Subject: [PATCH 3/3] Fix url --- .../30-authentication-and-user-management/30-keycloak.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md b/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md index fa6908eb..98cd9b0c 100644 --- a/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md +++ b/docs/admin/30-configuration/30-authentication-and-user-management/30-keycloak.md @@ -46,7 +46,7 @@ GRAPH_USERNAME_MATCH=none OC_EXCLUDE_RUN_SERVICES=idp ``` -Look [here](./10-example-idp.md#opencloud-configuration) for some more details about these settings. +Look [here](./10-external-idp.md#opencloud-configuration) for some more details about these settings. ## Client Configuration