From 84cf4196e25ea61af4739b3a73c40d1ce6b9157b Mon Sep 17 00:00:00 2001 From: stratself Date: Mon, 14 Sep 2026 05:27:53 +0000 Subject: [PATCH] docs(auth): Fix wordings and add links to admin commands * Add confirmed email + reCAPTCHA registration method as well --- docs/authentication/internal.mdx | 21 +++++++++++---------- docs/authentication/oidc.mdx | 10 +++++----- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/authentication/internal.mdx b/docs/authentication/internal.mdx index 727ea5cfb..881d334bc 100644 --- a/docs/authentication/internal.mdx +++ b/docs/authentication/internal.mdx @@ -8,17 +8,18 @@ Registration is disabled by default. To enable it, set `allow_registration = tru | Method | Description | Additional configuration needed | | ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| 1 | Admin-issued tokens (recommended) | None. Use the `!admin issue token` command | +| 1 | Admin-issued tokens (recommended) | None. Use the [`!admin token issue`](../reference/admin/token#admin-token-issue) command | | 2 | Static registration token | `registration_token` or `registration_token_file` | | 3 | reCAPTCHA-only registration | `recaptcha_site_key` and `recaptcha_private_site_key` | -| 4 | Static token + reCAPTCHA | Methods 2 + 3 | -| 5 | Static token + email | Method 2 + `require_email_for_token_registration = true` in `[global.smtp]`. See [Email configuration](#email-configuration) | -| 6 | Static token + email + reCAPTCHA | Methods 3 + 5 | -| 7 | Email only | `require_email_for_registration = true` in `[global.smtp]` section. See [Email configuration](#email-configuration) | +| 4 | Email only registration | `require_email_for_registration = true` in `[global.smtp]` section. See [Email configuration](#email-configuration) | +| 5 | Static token + reCAPTCHA | Methods 2 + 3 | +| 6 | Email + reCAPTCHA | Methods 3 + 4 | +| 7 | Static token + email | Method 2 + `require_email_for_token_registration = true` in `[global.smtp]`. See [Email configuration](#email-configuration) | +| 8 | Static token + email + reCAPTCHA | Methods 3 + 7 | Users can register on Continuwiity's account management page, or directly within a Matrix client if legacy login is enabled. -Admin-issued tokens are the recommended method of registration. These tokens can be scoped with an expiry duration or maximum times used, and are suited for private/invite-only homeservers. See the `!admin token` commands for more details. +Admin-issued tokens are the recommended method of registration. These tokens can be scoped with an expiry duration or maximum times used, and are suited for private/invite-only homeservers. See the [`!admin token`](../reference/admin/token) commands for more details. Other registration methods are meant for **untrusted, public registration**. Care must be taken when allowing these modes of operation. @@ -37,13 +38,13 @@ connection_uri = "smtps://john%40example.com:password@mail.example.net:465" sender = "John's Continuwuity server " ``` -A user's email address can also be modified by the `!admin users change-email` command. To view current user-email associations, use the `!admin users get-email` and `!admin users get-user-by-email` command. +A user's email address can also be modified by the [`!admin users change-email`](../reference/admin/users#admin-users-change-email) command. To view current user-email associations, use the `!admin users get-email` and `!admin users get-user-by-email` command. -Use `!admin debug send-test-email` to test that your email setup is working. +Use [`!admin debug send-test-email`](../reference/admin/debug#admin-debug-send-test-email) to test that your email setup is working. ## Password resets Password resets in Continuwuity can be made via: -- Self-service password resets. This requires a user's email to be set up and verified. -- Using the `!admin users reset-password` command. +- Self-service password resets. This requires a user's email to have been set up and verified. +- Using the [`!admin users reset-password`](../reference/admin/users#admin-users-reset-password) command. diff --git a/docs/authentication/oidc.mdx b/docs/authentication/oidc.mdx index 97cf09cfc..64c47d005 100644 --- a/docs/authentication/oidc.mdx +++ b/docs/authentication/oidc.mdx @@ -6,7 +6,7 @@ Continuwuity supports delegating user authentication to an external identity pro 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 be linked with only **one** OIDC subject claim at a time. Linked accounts will also lose the ability to self-deactivate. +An account on the homeserver can be linked with only **one** OIDC subject claim (i.e. one account on the OIDC side) at a time. Linking an account will also disable its ability for do self-deactivation. ## Instructions @@ -74,15 +74,15 @@ Continuwuity offers several additional configuration options to tweak its integr ### Minting tokens for non-OIDC accounts -With OIDC delegation enabled, accounts without an OIDC mapping can still be created (via `!admin users create`), 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 their local password to work, which can be set with `!admin users reset-password`. +With OIDC delegation enabled, accounts without an OIDC mapping can still be created (via `!admin users create`), but will not be able to log in to the homeserver. To accommodate this, homeserver admins can use the [`!admin users issue-token`](../reference/admin/users#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`](../reference/admin/users#admin-users-reset-password). ### Decommissioning OIDC delegation -It is possible to revert to using the internal database for authentication. First, uncomment 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. +It is possible to revert to using the internal database for authentication. First, uncomment the `[global.oauth.oidc]` section in your config file and restart the homeserver. Then, execute the [`!admin users reset-password --convert-to-local-account`](../reference/admin/users#admin-users-reset-password) for each user, to assign them a local password and convert their linked accounts into local ones. ### Manually linking users to OIDC claims -To view associations between local users and their linked Subject Identifier (i.e. the unique ID of the account on the OIDC provider's side), issue the following command: +To view associations between local users and their linked Subject Identifier claim (i.e. the unique ID of the account on the OIDC provider's side), issue the following command: ``` !admin query raw raw-iter openidsubject_localpart @@ -90,7 +90,7 @@ To view associations between local users and their linked Subject Identifier (i. ("ba543628-e6a5-45d8-9bd2-6cc497400136", "jane") ``` -These associations can be changed manually with the `!admin oidc` commands, which is useful to debug some account linkage issues. For example, to link the user `jane` to a new Subject Identifier of `721c36a8-ce04-4474-8e97-b62655b07340`: +These associations can be changed manually with the [`!admin oidc`](../reference/admin/oidc) commands, which is 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`: ``` !admin oidc unlink ba543628-e6a5-45d8-9bd2-6cc497400136