@@ -0,0 +1,40 @@
+# Registration

@@ -0,0 +6,4 @@
+
+Continuwuity implements the following authentication flows:
+
+- **OAuth login** (also known as **next-gen auth**): clients redirect the user to Continuwuity's login/signup page.

@@ -0,0 +7,4 @@
+Continuwuity implements the following authentication flows:
+
+- **OAuth login** (also known as **next-gen auth**): clients redirect the user to Continuwuity's login/signup page.
+- **Legacy login** (also known as the **UIAA** framework): clients logs in/signs up directly to the server via its own UI.

@@ -0,0 +13,4 @@
+
+:::important Configure your client well-known for OAuth logins
+
+To ensure OAuth logins work, Continuwuity must know the path from which its Client-Server API is being served from:

@@ -0,0 +1,49 @@
+# Internal authentication
+
+Continuwuity by default comes with an internal database for user authentication. Using the internal database allows for self-servicing of account registration, linking emails, and password resets.

@@ -0,0 +18,4 @@
+
+Registrations can be made via Continuwuity's account management page, as well as in-band from 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.

@@ -0,0 +16,4 @@
+| 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)          |
+
+Registrations can be made via Continuwuity's account management page, as well as in-band from within a Matrix client (if legacy login is enabled).

@@ -0,0 +6,4 @@
+
+Continuwuity implements the following authentication flows:
+
+- **OAuth login** (also known as **next-gen auth**): clients redirect the user to Continuwuity's own login and registration page to complete the authentication process.

@@ -0,0 +4,4 @@
+
+## Registration
+
+Registration is disabled by default. To enable it, set `allow_registration = true` in your config file and configure at least one of the registration methods below.

@@ -0,0 +17,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.

@@ -0,0 +14,4 @@
+
+### Configuring the OIDC provider
+
+This guide will use [**kanidm**][kanidm] as an example, but the described steps are broadly applicable to other identity providers. Contributions for them are welcome.

@@ -0,0 +74,4 @@
+
+### 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`](../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).

@@ -0,0 +78,4 @@
+
+### 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`](../reference/admin/users#admin-users-reset-password) for each user, to assign them a local password and convert their linked accounts into local ones.

@@ -0,0 +9,4 @@
+- **OAuth login** (also known as **next-gen auth**): clients redirect the user to Continuwuity's own login and registration page to complete the authentication process.
+- **Legacy login** (also known as the **UIAA** framework): clients provide their own UI to log in to or register with the server directly.
+
+Different sets of clients support different flows, but most clients are moving towards next-gen auth. One can set which login mode(s) are allowed via the `compatibility_mode` variable of the `[global.oauth]` config file section.

@@ -0,0 +25,4 @@
+
+## Email configuration
+
+Continuwuity can be configured to send emails via an SMTP relay of your choice. These are used for verifying user email addresses and sending password resets links to them.

@@ -0,0 +6,4 @@
+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 (i.e. one account on the OIDC side) at a time. Linking an account will also disable its ability to do self-deactivation.

@@ -0,0 +48,4 @@
+
+### Configuring Continuwuity
+
+Configure Continuwuity with the client ID, client secret, and discovery URL provided from the steps above. 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.

@@ -0,0 +78,4 @@
+
+### Manually linking users to OIDC claims
+
+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:

@@ -0,0 +86,4 @@
+("ba543628-e6a5-45d8-9bd2-6cc497400136", "jane")
+```
+
+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`:

@@ -0,0 +98,4 @@
+
+### 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`](../reference/admin/users#admin-users-reset-password) for each user, to assign them a local password and convert their linked accounts into local ones.

@@ -0,0 +12,4 @@
+| 2      | Static registration token         | `registration_token` or `registration_token_file`                                                                            |
+| 3      | reCAPTCHA-only registration       | `recaptcha_site_key` and `recaptcha_private_site_key`                                                                        |
+| 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                                                                                                                |

@@ -0,0 +17,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 Continuwuity's account management page, or directly within a Matrix client if legacy login is enabled.

@@ -0,0 +76,4 @@
+
+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`](../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).
+
+### Manually linking users to OIDC claims

@@ -0,0 +1,35 @@
+# Authentication
+
+This chapter describes various ways to authenticate to Continuwuity.

@@ -0,0 +7,4 @@
+Continuwuity implements the following authentication flows:
+
+- **OAuth login** (also known as **next-gen auth**): clients redirect the user to Continuwuity's own login and registration page to complete the authentication process.
+- **Legacy login** (also known as the **UIAA** framework): clients provide their own UI to log in to or register with the server directly.

@@ -0,0 +28,4 @@
+
+Continuwuity can read user authentication data from the following sources:
+
+- **Internal database** - this is the default setup for Continuwuity. It allows for registration, email, and password reset self-service. See the [**internal authentication documentation**](./authentication/internal).