Skip to content

Document some of the requirements we currently have on the IDP #450

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

Merged
rhafer merged 1 commit into from
Sep 2, 2025
Merged

Document some of the requirements we currently have on the IDP #450

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
44 changes: 39 additions & 5 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 @@ -8,16 +8,42 @@ draft: false

# Integrating external OpenID Connect Identity Providers

The following environment variables are relevant when connecting OpenCloud to an external IDP
## 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.

This is the list of minimal requirements that an IDP needs to fulfill in order
to work with OpenCloud:

- All clients provided by OpenCloud ([Web](https://github.com/opencloud-eu/web/),
[Desktop](https://github.com/opencloud-eu/desktop/), [Android](https://github.com/opencloud-eu/android/)
and [iOS](https://github.com/opencloud-eu/ios/)), are implemented as public clients using the
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 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.

- `OC_OIDC_ISSUER`: Set this to the issuer URL of the external Identity Provider
- `OC_EXCLUDE_RUN_SERVICES`: To disable the built-in Identity Provider set this to `idp`
- `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.
- `PROXY_OIDC_REWRITE_WELLKNOWN`: Set this to `true` to expose the Identity
Copy link
Member

@dragotin dragotin Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence does not really explain. Where is the identity exposed? Why?

Copy link
Member Author

@rhafer rhafer Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not any identity that is being exposed. It's the "Identity Provider's well-known/openid-configuration endpoint.

Reworded, hth.

Copy link
Member

@dragotin dragotin Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add an real-world example configuration here with a little description?

Copy link
Member Author

@rhafer rhafer Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add a link to the keycloak chapter. I think that should do it.

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.
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.
- `PROXY_USER_OIDC_CLAIM` and `PROXY_USER_CS3_CLAIM`: These two variables
configure how the users mapped between the Identity Provider and OpenCloud.
`PROXY_USER_OIDC_CLAIM` defines the OIDC claim that OpenCloud uses to
Expand All @@ -42,6 +68,14 @@ The following environment variables are relevant when connecting OpenCloud to an

### 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.
:::

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`
Expand Down