From 0adfd32b0c28071932c74a0fb4a9185d459bc7b1 Mon Sep 17 00:00:00 2001 From: Freek Date: Mon, 12 Oct 2026 19:40:37 +0200 Subject: [PATCH] docs(oidc): Simplify, deduplicate and improve consistency --- docs/authentication/oidc.mdx | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/authentication/oidc.mdx b/docs/authentication/oidc.mdx index f238c6364..5c64a0eb1 100644 --- a/docs/authentication/oidc.mdx +++ b/docs/authentication/oidc.mdx @@ -16,18 +16,18 @@ A simple OIDC configuration is as easy as creating a new OIDC application in you ### Configuring the OIDC provider -This guide will cover [**Kanidm**][kanidm] and [**Authelia**][authelia], but the described steps are broadly applicable to other identity providers. Contributions for them are welcome. +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`. -First, create a new application for Continuwuity in your identity provider. +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. -# 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 ``` @@ -37,22 +37,23 @@ Configure the redirect URL that Continuwuity uses. 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. +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. Other identity providers may show this information in their web UI. +Find the client secret that was generated. ```sh kanidm system oauth2 show-basic-secret c10y d1qgx352kkuvs1j70b6w293d65x68jve1f7b27fyk90gjhpr ``` -If you followed these steps, the discovery URL for KanIDM is: https://idm.example.com/oauth2/openid/c10y +Now the discovery URL for KanIDM is: https://idm.yourdomain.com/oauth2/openid/c10y + 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: @@ -72,8 +73,6 @@ docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 -- Authelia only needs to know the digest (hash) of the secret, whereas Continuwuity requires the secret itself. -Also 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` for that (your server name in this case may be `yourdomain.com`). - 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 @@ -90,16 +89,13 @@ identity_providers: 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`. -The discovery URL that continuwuity can use with Authelia is simply the root domain at which your Authelia can be reached by clients, which should be something like `https://authelia.example.com`. -Whichever identity provider you\'re using, you should now have 3 things, which you\'ll need in the next section to configure Continuwuity itself: - -- Client Identifier (or client id) -- Client Secret -- Discovery URL [kanidm]: https://kanidm.com [authelia]: https://www.authelia.com