docs: Add guide on configuring OIDC

2026-07-10 19:22:00 +00:00 · 2026-07-07 10:13:26 -04:00
parent 7cb76a491f
commit e3cf7debae
2 changed files with 80 additions and 0 deletions
@@ -0,0 +1,22 @@
+[
+    {
+        "type": "file",
+        "name": "delegation",
+        "label": "Delegation / split-domain"
+    },
+    {
+        "type": "file",
+        "name": "dns",
+        "label": "DNS tuning (recommended)"
+    },
+    {
+        "type": "file",
+        "name": "performance",
+        "label": "Performance tuning"
+    },
+    {
+        "type": "file",
+        "name": "oidc",
+        "label": "Delegated authentication"
+    }
+]
@@ -0,0 +1,58 @@
+# Configuring delegated authentication
+
+Continuwuity supports delegating user authentication to an external identity provider that implements the OpenID Connect specification, such as Authentik, kanidm, or Keycloak.
+
+:::warning{title="OIDC versus OAuth, and supported clients"}
+**OIDC** is not to be confused with **OAuth**. In the context of Matrix, OAuth is the protocol that Matrix clients use to authenticate with the _homeserver_. OIDC is the protocol that the _homeserver_ uses to communicate with the _identity provider_. Continuwuity supports OAuth by default, alongside the legacy **UIAA** authentication framework.
+
+When OIDC is configured, Continuwuity will disable its support for UIAA. **Only clients that support OAuth**, such as
+the Element family of clients, will be able to log in when OIDC is configured. If your client of choice shows an error
+when you try to log in after configuring OIDC, it likely does not support OAuth. This is an issue with your client, not
+Continuwuity, and should be reported to your client's developers.
+:::
+
+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. This guide will use kanidm as an example, but the described steps are broadly applicable to other identity providers.
+
+First, create a new application for Continuwuity in your identity provider.
+```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.
+# Use the domain that Continuwuity is actually running on, even if you've configured delegation.
+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. Other identity providers may not require this step.
+```sh
+kanidm system oauth2 update-scope-map c10y idm_all_persons openid
+```
+
+Find the client secret that was generated. Other identity providers may show this information in their web UI.
+```sh
+kanidm system oauth2 show-basic-secret c10y
+d1qgx352kkuvs1j70b6w293d65x68jve1f7b27fyk90gjhpr
+```
+
+Configure Continuwuity with the client ID, client secret, and discovery URL. kanidm has a different discovery URL for each client, but other identity providers may have a single discovery URL at the root of their domain.
+
+```toml
+[global.oauth.oidc]
+
+# `/.well-known/openid-configuration` will be appended automatically
+discovery_url = "https://idm.example.com/oauth2/openid/c10y"
+
+# This may be randomly generated by your identity provider. kanidm requires
+# you to set it manually when you create the application.
+client_id = "c10y"
+
+# From the previous step
+client_secret = "d1qgx352kkuvs1j70b6w293d65x68jve1f7b27fyk90gjhpr"
+```
+
+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, you will be prompted to choose a user ID -- to link your existing account, enter its user ID, and then your old password when prompted.
+
+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.