docs: Fix nitpicks

docs/_meta.json

@@ -36,8 +36,8 @@
     },
     {
         "type": "dir",
-        "name": "advanced",
-        "label": "Advanced"
+        "name": "guides",
+        "label": "Guides"
     },
     "security",
     {

docs/_nav.json

@@ -1,8 +1,8 @@
 [
     {
-        "text": "Guide",
+        "text": "Documentation",
         "link": "/introduction",
-        "activeMatch": "^/(introduction|configuration|deploying|calls|appservices|maintenance|troubleshooting|advanced)"
+        "activeMatch": "^/(introduction|configuration|deploying|calls|appservices|maintenance|troubleshooting|guides)"
     },
     {
         "text": "Development",

docs/deploying/docker.mdx

@@ -44,7 +44,7 @@ ### Prerequisites
     - Alternatively, if you want both client and federation traffic on `:443`, you can configure `CONTINUWUITY_WELL_KNOWN` following some of the [examples](#choose-your-reverse-proxy) below.
 
 :::tip Split-domain setups
-For more setups with `.well-known` delegation and split-domain deployments, consult the [Delegation/Split-domain](../advanced/delegation) page.
+For more setups with `.well-known` delegation and split-domain deployments, consult the [Delegation/Split-domain](../guides/delegation) page.
 :::
 
 ## Docker Compose
@@ -79,7 +79,7 @@ ### Choose Your Reverse Proxy
 nameserver 1.1.1.1
 ```
 
-Consult the [**DNS tuning guide (recommended)**](../advanced/dns.mdx) for full solutions to this issue.
+Consult the [**DNS tuning guide (recommended)**](../guides/dns.mdx) for full solutions to this issue.
 :::
 
 #### Caddy (using Caddyfile)
@@ -269,7 +269,7 @@ ### Accessing the Server's Console
 
 ## Next steps
 
-- For smooth federation, set up a caching resolver according to the [**DNS tuning guide**](../advanced/dns.mdx) (recommended)
+- For smooth federation, set up a caching resolver according to the [**DNS tuning guide**](../guides/dns.mdx) (recommended)
 - To set up Audio/Video communication, see the [**Calls**](../calls.mdx) page.
 - Consult the [Maintenance](../maintenance.mdx) page for guidance on maintaining your homeserver.
 - If you want to set up an appservice, take a look at the [**Appservice Guide**](../appservices.mdx).

docs/deploying/generic.mdx

@@ -170,7 +170,7 @@ ## Exposing ports in the firewall or the router
 are: `ufw allow 8448/tcp` and `ufw allow 443/tcp`.
 
 :::tip Alternative port/domain setups
-If you would like to use only port 443, a different port, or a subdomain for the homeserver, you will need to set up `.well-known` delegation. Consult the `[global.well_known]` section of the config file, and the [**Delegation/Split-domain**](../advanced/delegation) page to learn more about these kinds of deployments.
+If you would like to use only port 443, a different port, or a subdomain for the homeserver, you will need to set up `.well-known` delegation. Consult the `[global.well_known]` section of the config file, and the [**Delegation/Split-domain**](../guides/delegation) page to learn more about these kinds of deployments.
 :::
 
 ## Setting up the Reverse Proxy
@@ -300,7 +300,8 @@ # For client-server endpoints
 
 ## What's next?
 
-- For smooth federation, set up a caching resolver according to the [**DNS tuning guide**](../advanced/dns.mdx) (recommended)
+- For smooth federation, set up a caching resolver according to the [**DNS tuning guide**](../guides/dns.mdx) (recommended)
+- To configure OIDC login with an identity provider, see the [**delegated authentication guide**](../guides/oidc.mdx).
 - For Audio/Video call functionality see the [**Calls**](../calls.md) page.
 - Consult the [Maintenance](../maintenance.mdx) page for guidance on maintaining your homeserver.
 - If you want to set up an appservice, take a look at the [**Appservice Guide**](../appservices.md).

docs/deploying/rpm.mdx

@@ -64,7 +64,7 @@ ### Nightly releases
 Nightly packages for openSUSE are **not currently available**.
 
 If there is an ongoing need for these, please ask in `#continuwuity:continuwuity.org` or [open an issue on Forgejo](https://forgejo.ellis.link/continuwuation/continuwuity/issues/new).
-In the meantime, you may follow the [generic deployment instructions](deployment/generic).
+In the meantime, you may follow the [generic deployment instructions](generic).
 </Tab>
 </Tabs>
 

docs/guides/_meta.json

@@ -13,6 +13,10 @@
         "type": "file",
         "name": "performance",
         "label": "Performance tuning"
+    },
+    {
+        "type": "file",
+        "name": "oidc",
+        "label": "Delegated authentication"
     }
-
 ]

docs/guides/delegation.mdx

@@ -58,6 +58,13 @@ # Defaults to members of the admin room if unset
 
 To enable full discovery, you will need to reverse proxy these paths from the base domain back to Continuwuity.
 
+:::warning
+If you choose to serve the well-known files directly through your reverse proxy, and you are
+using delegation, you must still set the `global.well_known.client` configuration option to
+the domain you're delegating to. Continuwuity needs to know the domain it runs on for OAuth-compatible
+clients to work correctly.
+:::
+
 ## Reverse proxying well-known files to Continuwuity
 
 <details>

docs/guides/oidc.mdx

@@ -0,0 +1,56 @@
+# 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 legacy authentication. **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 clients can reach Continuwuity at, which may not be the same as your server name
+# if you have configured well-known 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.

docs/troubleshooting.mdx

@@ -60,7 +60,7 @@ ### DNS server overload
 
 Matrix federation is extremely heavy and sends wild amounts of DNS requests. This makes normal resolvers like the ones above unsuitable for its activity. Ultimately, the best solution/fix for this is to selfhost a high quality caching DNS resolver such as Unbound, and configure Continuwuity to use it.
 
-Follow the [**DNS tuning guide**](./advanced/dns) for details on setting it up.
+Follow the [**DNS tuning guide**](./guides/dns) for details on setting it up.
 
 ### Intermittent federation failures to a specific server