Skip to content

rework the external-idp and keycloak docs #971

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Svanvith wants to merge 1 commit into
base: main
Choose a base branch
from
+127 −124
Open

rework the external-idp and keycloak docs #971

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 81 additions & 91 deletions docs/admin/configuration/authentication-and-user-management/external-idp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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://<opencloud-domain>/.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
Expand Down Expand Up @@ -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`
79 changes: 46 additions & 33 deletions docs/admin/configuration/authentication-and-user-management/keycloak.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down