Matrix
Forgejo

    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.

    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.

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

    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.

    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.

    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.

    [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 for a complete list of options and documentation.