---
title: "Discover OIDC Client configuration via WebFinger"
---

* Status: accepted
* Deciders: [@TheOneRing @kulmann @rhafer @dragotin]
* Date: 2026-02-02

Reference: https://github.com/qsfera/server/pull/2072, https://github.com/qsfera-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
КуСфера with various existing identity providers. For example:

- Authentik basically creates a different issuer URL for each client. As КуСфера
  can only work with a single issuer URL, all КуСфера 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 КуСфера 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.qsfera.test&rel=http://openid.net/specs/connect/1.0/issuer&platform=desktop
```

### Server Response

```json
{
  "subject": "https://cloud.qsfera.test",
  "links": [{
    "rel": "http://openid.net/specs/connect/1.0/issuer",
    "href": "https://idp.example.com"
  }],
  "properties": {
    "http://qsfera.eu/ns/oidc/client_id": "desktop-client-id",
    "http://qsfera.eu/ns/oidc/scopes": ["openid", "profile", "email", "offline_access"]
  }
}
```

### Server configuration (suggestion)

To configure the КуСфера 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_SCOPES
WEBFINGER_DESKTOP_OIDC_CLIENT_ID
WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES
WEBFINGER_IOS_OIDC_CLIENT_ID
WEBFINGER_IOS_OIDC_CLIENT_SCOPES
WEBFINGER_WEB_OIDC_CLIENT_ID
WEBFINGER_WEB_OIDC_CLIENT_SCOPES
```

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.