continuwuity/docs/authentication/oidc.mdx

import { Tab, Tabs } from '@rspress/core/theme';

# Delegated authentication with OIDC

Continuwuity supports delegating user authentication to an external identity provider that implements the OpenID Connect (OIDC) specification, such as Authentik, Kanidm, or Keycloak.

:::important Delegated authentication and legacy logins
When delegated authentication is configured, Continuwuity will disable its support for legacy logins. **Only clients that support OAuth** will be able to login.
:::

An account on the homeserver can only be associated with one OIDC subject claim - that is, one account on the identity provider - at a time. Linking an account will also prevent the user from deactivating it themselves.

## Instructions

A simple OIDC configuration is as easy as creating a new OIDC application in your identity provider's settings and supplying Continuwuity with the client ID and client secret.

### Configuring the OIDC provider

This guide will cover [**Kanidm**][kanidm] and [**Authelia**][authelia], but the basic concepts apply to most identity providers. Contributions for them are welcome.

Before you start, note the domain that clients can reach Continuwuity at, which may not be the same as your server name if you have configured well-known delegation. In this example, we will use `https://matrix.yourdomain.com`.

<Tabs groupId="idp">
<Tab label="KanIDM">

Create a new application for continuwuity in kanidm.

```sh
# Here, `c10y` is the client ID that Kanidm will use, and `Continuwuity` is the display name.
# Other identity providers may generate a client ID for you.
kanidm system oauth2 create c10y Continuwuity https://matrix.yourdomain.com
```

Configure the redirect URL that Continuwuity uses.

```sh
kanidm system oauth2 add-redirect-url c10y https://matrix.yourdomain.com/_continuwuity/oidc/complete
```

Allow Continuwuity to request the `openid` scope.

```sh
kanidm system oauth2 update-scope-map c10y idm_all_persons openid
```

Find the client secret that was generated.
```sh
kanidm system oauth2 show-basic-secret c10y
d1qgx352kkuvs1j70b6w293d65x68jve1f7b27fyk90gjhpr
```

Now the discovery URL for KanIDM is: https://idm.yourdomain.com/oauth2/openid/c10y

</Tab>
<Tab label="Authelia">

These instructions assume you have already set up Authelia as an OIDC provider and are just adding Continuwuity to it. If you are looking how to set up your Authelia as an OIDC provider, [this article](https://blog.stonegarden.dev/articles/2025/06/authelia-oidc/) is very useful.
To create a new client in your identity provider, it is [recommended](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret) to randomly generate both the client id and client secret. The commands below should get you those:

```sh
# Generate client ID:
authelia crypto rand --length 72 --charset rfc3986
# or using Docker:
docker run --rm authelia/authelia:latest authelia crypto rand --length 72 --charset rfc3986
```

Generate the client secret (shown as password in output) and its digest:
```sh
authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
# or using Docker:
docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
```

Authelia only needs to know the digest (hash) of the secret, whereas Continuwuity requires the secret itself.

Now we have everything we need to add Continuwuity to Authelia's OIDC client configuration. Go to your Authelia configuration file, find the `identity_provers` block, and add to the `clients` list:

```yaml
identity_providers:
  oidc:
    jwks:
       # This part has the JWKs and is what you configured previously
       [...]
    clients:
      # Add this block below
      - client_name: continuwuity
        client_id: "client-id-goes-here"
        client_secret: "client-secret-DIGEST-goes-here"
        redirect_uris: ["https://matrix.yourdomain.com/_continuwuity/oidc/complete"]
        scopes: [openid]
```
Then restart Authelia to load the new configuration.

The discovery URL is simply the root domain at which your Authelia can be reached by clients, which should be something like `https://authelia.yourdomain.com`.

</Tab>
</Tabs>


[kanidm]: https://kanidm.com
[authelia]: https://www.authelia.com

### Configuring Continuwuity

Configure Continuwuity with the client ID, client secret, and discovery URL provided from the steps above.

```toml
[global.oauth.oidc]

# `/.well-known/openid-configuration` will be appended automatically
# Choose the appropriate option from below, not both
discovery_url = "https://your-discovery-url"

client_id = "your-client-id"

client_secret = "your-client-secret"
```

### Testing that it works

Finally, restart Continuwuity, and log out and back in again. Your client should prompt you to continue in your web browser and open a webpage with the Continuwuity logo that allows you to continue in your identity provider. Once you log in successfully there, you will be prompted to choose a user ID -- to link your existing account, enter its user ID, and then your old password.

Continuwuity offers several additional configuration options to tweak its integration with your identity provider. Review the `[global.oauth.oidc]` section towards the bottom of the [reference configuration](../reference/config) for a complete list of options and documentation.

## Advanced options

### Minting tokens for non-OIDC accounts

With OIDC delegation enabled, accounts without an OIDC mapping (such as bot accounts) can still be created via the admin commands, but will not be able to log in to the homeserver. To accommodate this, homeserver admins can use the [`!admin users issue-token`](../reference/admin/users#admin-users-issue-token) command to issue tokens for them. This command requires the account to have set a local password, which can be done with [`!admin users reset-password`](../reference/admin/users#admin-users-reset-password).

### Manually linking users to OIDC claims

To view associations between local users and their linked subject claim, issue the following command:

```
!admin query raw raw-iter openidsubject_localpart
("1d3fc994-3947-406d-b22c-0fc529baf235", "john")
("ba543628-e6a5-45d8-9bd2-6cc497400136", "jane")
```

These associations can be changed manually with the [`!admin oidc`](../reference/admin/oidc) commands, which are useful to debug some account linkage issues. For example, to link the user `jane` to a new Subject Identifier claim of `721c36a8-ce04-4474-8e97-b62655b07340`:

```
!admin oidc unlink ba543628-e6a5-45d8-9bd2-6cc497400136
Subject `ba543628-e6a5-45d8-9bd2-6cc497400136` unlinked.
!admin oidc link jane 721c36a8-ce04-4474-8e97-b62655b07340
Subject `721c36a8-ce04-4474-8e97-b62655b07340` linked to account @jane:example.com.
!admin query raw raw-iter openidsubject_localpart
("1d3fc994-3947-406d-b22c-0fc529baf235", "john")
("721c36a8-ce04-4474-8e97-b62655b07340", "jane")
```

### Decommissioning OIDC delegation

It is possible to revert to using the internal database for authentication. First, comment out the `[global.oauth.oidc]` section in your config file and restart the homeserver. Then, execute the [`!admin users reset-password --convert-to-local-account`](../reference/admin/users#admin-users-reset-password) for each user to assign them a local password and convert their linked accounts into local ones.