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.

The instructions below make the following assumptions:

- Continuwuity's base URL: `https://matrix.example.com`. Note that if you employ [well-known delegation](../guides/delegation), this must match the client well-known domain rather than your server name.
- OIDC provider's base URL: `https://idm.example.com`

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

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

Create a new application for continuwuity in kanidm. We will use `c10y` as the client ID.

```sh
kanidm system oauth2 create c10y Continuwuity https://matrix.example.com
```

Configure the redirect URL that Continuwuity uses.

```sh
kanidm system oauth2 add-redirect-url c10y https://matrix.example.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.example.com/oauth2/openid/c10y`

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

To create a new client in Authelia, it is [recommended][authelia-faq-client-secret] to randomly generate both the client id and client secret. The commands below should get you those:

<Tabs groupId="authelia-generate-client-details">
<Tab label="Bare Binary">
```sh
# Generate random value for Client ID
authelia crypto rand --length 72 --charset rfc3986
# Generate Client Secret (labeled Random Password) and its Digest
authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
```
</Tab>
<Tab label="Docker">
```sh
# Generate random value for Client ID
docker run --rm authelia/authelia:latest authelia crypto rand --length 72 --charset rfc3986
# Generate Client Secret (labeled Random Password) and its Digest
docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
```
</Tab>
</Tabs>

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

Go to your Authelia configuration file, find the `identity_provers` block, and add a block for Continuwuity 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 to the clients list
      - client_name: continuwuity
        client_id: "client-id-goes-here"
        # Use the client secret's DIGEST, not the client secret itself
        client_secret: "client-secret-DIGEST-goes-here"
        redirect_uris: ["https://matrix.example.com/_continuwuity/oidc/complete"]
        scopes: [openid]
```
Then restart Authelia to load the new configuration.

The discovery URL is simply the root domain of your Authelia, where it can be reached by clients, i.e. `https://idm.example.com`.

</Tab>
</Tabs>

[kanidm]: https://kanidm.com
[authelia]: https://www.authelia.com
[authelia-faq-client-secret]: https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret

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