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.
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, 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 and Authelia, but the basic concepts apply to most identity providers. Contributions for them are welcome.
Create a new application for continuwuity in kanidm. We will use c10y as the client ID.
Configure the redirect URL that Continuwuity uses.
Allow Continuwuity to request the openid scope.
Find the client secret that was generated.
Now the discovery URL for KanIDM is: https://idm.example.com/oauth2/openid/c10y
Configuring Continuwuity
Configure Continuwuity with the client ID, client secret, and discovery URL provided from the steps above.
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 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 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.
Manually linking users to OIDC claims
To view associations between local users and their linked subject claim, issue the following command:
These associations can be changed manually with the !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:
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 for each user to assign them a local password and convert their linked accounts into local ones.