-
Notifications
You must be signed in to change notification settings - Fork 162
adr: Document OIDC client parameter discovery #2253
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.
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
+89
−0
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| --- | ||
| title: "Discover OIDC Client configuration via WebFinger" | ||
| --- | ||
|
|
||
| * Status: accepted | ||
| * Deciders: [@TheOneRing @kulmann @rhafer @dragotin] | ||
| * Date: 2026-02-02 | ||
|
|
||
| Reference: https://github.com/opencloud-eu/opencloud/pull/2072, https://github.com/opencloud-eu/desktop/issues/217 | ||
|
|
||
| ## Context and Problem Statement | ||
|
|
||
| Up to now our client applications used hard-coded OIDC client configurations. | ||
| So it is not possible to change the client id that a client should use or the | ||
| list of scopes that a client needs to request. This makes it hard to integrate | ||
| OpenCloud with various existing identity providers. For example: | ||
|
|
||
| - Authentik basically creates a different issuer URL for each client. As OpenCloud | ||
| can only work with a single issuer URL, all OpenCloud clients need to use the | ||
| same client id to work with Authentik. | ||
| - Some IDPs (kanidm) are not able to work with user-supplied client ids. They generate | ||
| client ids automatically and do not allow to specify them manually. | ||
| - To make features like automatic role assignment work, clients need to request | ||
| specific scopes, depending on which exact IDP is used. | ||
|
|
||
| ## Decision Drivers | ||
|
|
||
| * Support broader set of IDPs | ||
| * avoid any manual configuration adjustments on the client side | ||
|
|
||
| ## Decision | ||
|
|
||
| Enhance the WebFinger service in OpenCloud to provide platform-specific OIDC | ||
| discovery, enabling clients to query for the correct OIDC `client_id` and | ||
| `scopes` based on their application type (e.g., web, desktop, android, ios). | ||
|
|
||
| This is achieved by allowing an additional `platform` query parameter to be used | ||
| when querying the WebFinger endpoint. The response will include the appropriate | ||
| `client_id` and `scopes` in the `properties` section of the response. | ||
|
|
||
| This is implemented in a backward-compatible way, so existing clients that do not | ||
| specify the `platform` parameter will continue to receive just the issuer information. | ||
|
|
||
| ## Example | ||
|
|
||
| ### Client Request | ||
|
|
||
| ``` | ||
| GET /.well-known/webfinger?resource=https://cloud.opencloud.test&rel=http://openid.net/specs/connect/1.0/issuer&platform=desktop | ||
| ``` | ||
|
|
||
| ### Server Response | ||
|
|
||
| ```json | ||
| { | ||
| "subject": "https://cloud.opencloud.test", | ||
| "links": [{ | ||
| "rel": "http://openid.net/specs/connect/1.0/issuer", | ||
| "href": "https://idp.example.com" | ||
| }], | ||
| "properties": { | ||
| "http://opencloud.eu/ns/oidc/client_id": "desktop-client-id", | ||
| "http://opencloud.eu/ns/oidc/scopes": ["openid", "profile", "email", "offline_access"] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
rhafer marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### Server configuration (suggestion) | ||
|
|
||
| To configure the OpenCloud server a couple of new config settings need to be introduced. This would | ||
| be two new settings per client, e.g.: | ||
|
|
||
|
|
||
| ``` | ||
| WEBFINGER_ANDROID_OIDC_CLIENT_ID | ||
| WEBFINGER_ANDROID_OIDC_CLIENT_SCOPE | ||
| WEBFINGER_DESKTOP_OIDC_CLIENT_ID | ||
| WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPE | ||
| WEBFINGER_IOS_OIDC_CLIENT_ID | ||
| WEBFINGER_IOS_OIDC_CLIENT_SCOPE | ||
| WEBFINGER_WEB_OIDC_CLIENT_ID | ||
| WEBFINGER_WEB_OIDC_CLIENT_SCOPE | ||
| ``` | ||
|
|
||
| Additionally for backwards compatibility the existing `WEB_OIDC_CLIENT_ID` and | ||
| `WEB_OIDC_CLIENT_SCOPE` settings should be used as fallback for the `web` | ||
| platform. Also we should make it easy to configure the same settings for all | ||
| platforms at once by using `OC_OIDC_CLIENT_ID` and `OC_OIDC_CLIENT_SCOPE` as | ||
| fallback for all platforms if the platform-specific settings are not set. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So how does OpenCloud get the information which client id to propagate to e.g. the Android app then?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will be a Server configuration variable
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added the new config settings here. Will also adapt the implementation to allow the fallbacks.