mirror of
https://git.anonymousland.org/anonymousland/synapse-product.git
synced 2024-09-07 23:11:59 +00:00
Improve documentation around user registration (#13640)
Update a bunch of the documentation for user registration, add some cross links, etc.
This commit is contained in:
parent
5e5c8150d7
commit
c4e29b6908
1
changelog.d/13640.doc
Normal file
1
changelog.d/13640.doc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Improve documentation around user registration.
|
@ -5,9 +5,9 @@ non-interactive way. This is generally used for bootstrapping a Synapse
|
|||||||
instance with administrator accounts.
|
instance with administrator accounts.
|
||||||
|
|
||||||
To authenticate yourself to the server, you will need both the shared secret
|
To authenticate yourself to the server, you will need both the shared secret
|
||||||
(`registration_shared_secret` in the homeserver configuration), and a
|
([`registration_shared_secret`](../configuration/config_documentation.md#registration_shared_secret)
|
||||||
one-time nonce. If the registration shared secret is not configured, this API
|
in the homeserver configuration), and a one-time nonce. If the registration
|
||||||
is not enabled.
|
shared secret is not configured, this API is not enabled.
|
||||||
|
|
||||||
To fetch the nonce, you need to request one from the API:
|
To fetch the nonce, you need to request one from the API:
|
||||||
|
|
||||||
|
@ -506,9 +506,13 @@ email will be disabled.
|
|||||||
|
|
||||||
### Registering a user
|
### Registering a user
|
||||||
|
|
||||||
The easiest way to create a new user is to do so from a client like [Element](https://element.io/).
|
One way to create a new user is to do so from a client like
|
||||||
|
[Element](https://element.io/). This requires registration to be enabled via
|
||||||
|
the
|
||||||
|
[`enable_registration`](../usage/configuration/config_documentation.md#enable_registration)
|
||||||
|
setting.
|
||||||
|
|
||||||
Alternatively, you can do so from the command line. This can be done as follows:
|
Alternatively, you can create new users from the command line. This can be done as follows:
|
||||||
|
|
||||||
1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was
|
1. If synapse was installed via pip, activate the virtualenv as follows (if Synapse was
|
||||||
installed via a prebuilt package, `register_new_matrix_user` should already be
|
installed via a prebuilt package, `register_new_matrix_user` should already be
|
||||||
@ -520,7 +524,7 @@ Alternatively, you can do so from the command line. This can be done as follows:
|
|||||||
```
|
```
|
||||||
2. Run the following command:
|
2. Run the following command:
|
||||||
```sh
|
```sh
|
||||||
register_new_matrix_user -c homeserver.yaml http://localhost:8008
|
register_new_matrix_user -c homeserver.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
This will prompt you to add details for the new user, and will then connect to
|
This will prompt you to add details for the new user, and will then connect to
|
||||||
@ -533,12 +537,13 @@ Make admin [no]:
|
|||||||
Success!
|
Success!
|
||||||
```
|
```
|
||||||
|
|
||||||
This process uses a setting `registration_shared_secret` in
|
This process uses a setting
|
||||||
`homeserver.yaml`, which is shared between Synapse itself and the
|
[`registration_shared_secret`](../usage/configuration/config_documentation.md#registration_shared_secret),
|
||||||
`register_new_matrix_user` script. It doesn't matter what it is (a random
|
which is shared between Synapse itself and the `register_new_matrix_user`
|
||||||
value is generated by `--generate-config`), but it should be kept secret, as
|
script. It doesn't matter what it is (a random value is generated by
|
||||||
anyone with knowledge of it can register users, including admin accounts,
|
`--generate-config`), but it should be kept secret, as anyone with knowledge of
|
||||||
on your server even if `enable_registration` is `false`.
|
it can register users, including admin accounts, on your server even if
|
||||||
|
`enable_registration` is `false`.
|
||||||
|
|
||||||
### Setting up a TURN server
|
### Setting up a TURN server
|
||||||
|
|
||||||
|
@ -1873,8 +1873,8 @@ See [here](../../CAPTCHA_SETUP.md) for full details on setting up captcha.
|
|||||||
---
|
---
|
||||||
### `recaptcha_public_key`
|
### `recaptcha_public_key`
|
||||||
|
|
||||||
This homeserver's ReCAPTCHA public key. Must be specified if `enable_registration_captcha` is
|
This homeserver's ReCAPTCHA public key. Must be specified if
|
||||||
enabled.
|
[`enable_registration_captcha`](#enable_registration_captcha) is enabled.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
@ -1883,7 +1883,8 @@ recaptcha_public_key: "YOUR_PUBLIC_KEY"
|
|||||||
---
|
---
|
||||||
### `recaptcha_private_key`
|
### `recaptcha_private_key`
|
||||||
|
|
||||||
This homeserver's ReCAPTCHA private key. Must be specified if `enable_registration_captcha` is
|
This homeserver's ReCAPTCHA private key. Must be specified if
|
||||||
|
[`enable_registration_captcha`](#enable_registration_captcha) is
|
||||||
enabled.
|
enabled.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
@ -1893,9 +1894,11 @@ recaptcha_private_key: "YOUR_PRIVATE_KEY"
|
|||||||
---
|
---
|
||||||
### `enable_registration_captcha`
|
### `enable_registration_captcha`
|
||||||
|
|
||||||
Set to true to enable ReCaptcha checks when registering, preventing signup
|
Set to `true` to require users to complete a CAPTCHA test when registering an account.
|
||||||
unless a captcha is answered. Requires a valid ReCaptcha public/private key.
|
Requires a valid ReCaptcha public/private key.
|
||||||
Defaults to false.
|
Defaults to `false`.
|
||||||
|
|
||||||
|
Note that [`enable_registration`](#enable_registration) must also be set to allow account registration.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
@ -1971,9 +1974,21 @@ Registration can be rate-limited using the parameters in the [Ratelimiting](#rat
|
|||||||
---
|
---
|
||||||
### `enable_registration`
|
### `enable_registration`
|
||||||
|
|
||||||
Enable registration for new users. Defaults to false. It is highly recommended that if you enable registration,
|
Enable registration for new users. Defaults to `false`.
|
||||||
you use either captcha, email, or token-based verification to verify that new users are not bots. In order to enable registration
|
|
||||||
without any verification, you must also set `enable_registration_without_verification` to true.
|
It is highly recommended that if you enable registration, you set one or more
|
||||||
|
or the following options, to avoid abuse of your server by "bots":
|
||||||
|
|
||||||
|
* [`enable_registration_captcha`](#enable_registration_captcha)
|
||||||
|
* [`registrations_require_3pid`](#registrations_require_3pid)
|
||||||
|
* [`registration_requires_token`](#registration_requires_token)
|
||||||
|
|
||||||
|
(In order to enable registration without any verification, you must also set
|
||||||
|
[`enable_registration_without_verification`](#enable_registration_without_verification).)
|
||||||
|
|
||||||
|
Note that even if this setting is disabled, new accounts can still be created
|
||||||
|
via the admin API if
|
||||||
|
[`registration_shared_secret`](#registration_shared_secret) is set.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
@ -1981,88 +1996,21 @@ enable_registration: true
|
|||||||
```
|
```
|
||||||
---
|
---
|
||||||
### `enable_registration_without_verification`
|
### `enable_registration_without_verification`
|
||||||
|
|
||||||
Enable registration without email or captcha verification. Note: this option is *not* recommended,
|
Enable registration without email or captcha verification. Note: this option is *not* recommended,
|
||||||
as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect
|
as registration without verification is a known vector for spam and abuse. Defaults to `false`. Has no effect
|
||||||
unless `enable_registration` is also enabled.
|
unless [`enable_registration`](#enable_registration) is also enabled.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
enable_registration_without_verification: true
|
enable_registration_without_verification: true
|
||||||
```
|
```
|
||||||
---
|
---
|
||||||
### `session_lifetime`
|
|
||||||
|
|
||||||
Time that a user's session remains valid for, after they log in.
|
|
||||||
|
|
||||||
Note that this is not currently compatible with guest logins.
|
|
||||||
|
|
||||||
Note also that this is calculated at login time: changes are not applied retrospectively to users who have already
|
|
||||||
logged in.
|
|
||||||
|
|
||||||
By default, this is infinite.
|
|
||||||
|
|
||||||
Example configuration:
|
|
||||||
```yaml
|
|
||||||
session_lifetime: 24h
|
|
||||||
```
|
|
||||||
----
|
|
||||||
### `refresh_access_token_lifetime`
|
|
||||||
|
|
||||||
Time that an access token remains valid for, if the session is using refresh tokens.
|
|
||||||
|
|
||||||
For more information about refresh tokens, please see the [manual](user_authentication/refresh_tokens.md).
|
|
||||||
|
|
||||||
Note that this only applies to clients which advertise support for refresh tokens.
|
|
||||||
|
|
||||||
Note also that this is calculated at login time and refresh time: changes are not applied to
|
|
||||||
existing sessions until they are refreshed.
|
|
||||||
|
|
||||||
By default, this is 5 minutes.
|
|
||||||
|
|
||||||
Example configuration:
|
|
||||||
```yaml
|
|
||||||
refreshable_access_token_lifetime: 10m
|
|
||||||
```
|
|
||||||
---
|
|
||||||
### `refresh_token_lifetime: 24h`
|
|
||||||
|
|
||||||
Time that a refresh token remains valid for (provided that it is not
|
|
||||||
exchanged for another one first).
|
|
||||||
This option can be used to automatically log-out inactive sessions.
|
|
||||||
Please see the manual for more information.
|
|
||||||
|
|
||||||
Note also that this is calculated at login time and refresh time:
|
|
||||||
changes are not applied to existing sessions until they are refreshed.
|
|
||||||
|
|
||||||
By default, this is infinite.
|
|
||||||
|
|
||||||
Example configuration:
|
|
||||||
```yaml
|
|
||||||
refresh_token_lifetime: 24h
|
|
||||||
```
|
|
||||||
---
|
|
||||||
### `nonrefreshable_access_token_lifetime`
|
|
||||||
|
|
||||||
Time that an access token remains valid for, if the session is NOT
|
|
||||||
using refresh tokens.
|
|
||||||
|
|
||||||
Please note that not all clients support refresh tokens, so setting
|
|
||||||
this to a short value may be inconvenient for some users who will
|
|
||||||
then be logged out frequently.
|
|
||||||
|
|
||||||
Note also that this is calculated at login time: changes are not applied
|
|
||||||
retrospectively to existing sessions for users that have already logged in.
|
|
||||||
|
|
||||||
By default, this is infinite.
|
|
||||||
|
|
||||||
Example configuration:
|
|
||||||
```yaml
|
|
||||||
nonrefreshable_access_token_lifetime: 24h
|
|
||||||
```
|
|
||||||
---
|
|
||||||
### `registrations_require_3pid`
|
### `registrations_require_3pid`
|
||||||
|
|
||||||
If this is set, the user must provide all of the specified types of 3PID when registering.
|
If this is set, users must provide all of the specified types of 3PID when registering an account.
|
||||||
|
|
||||||
|
Note that [`enable_registration`](#enable_registration) must also be set to allow account registration.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
@ -2110,9 +2058,11 @@ enable_3pid_lookup: false
|
|||||||
|
|
||||||
Require users to submit a token during registration.
|
Require users to submit a token during registration.
|
||||||
Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md).
|
Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md).
|
||||||
Note that `enable_registration` must be set to true.
|
|
||||||
Disabling this option will not delete any tokens previously generated.
|
Disabling this option will not delete any tokens previously generated.
|
||||||
Defaults to false. Set to true to enable.
|
Defaults to `false`. Set to `true` to enable.
|
||||||
|
|
||||||
|
|
||||||
|
Note that [`enable_registration`](#enable_registration) must also be set to allow account registration.
|
||||||
|
|
||||||
Example configuration:
|
Example configuration:
|
||||||
```yaml
|
```yaml
|
||||||
@ -2121,8 +2071,13 @@ registration_requires_token: true
|
|||||||
---
|
---
|
||||||
### `registration_shared_secret`
|
### `registration_shared_secret`
|
||||||
|
|
||||||
If set, allows registration of standard or admin accounts by anyone who
|
If set, allows registration of standard or admin accounts by anyone who has the
|
||||||
has the shared secret, even if registration is otherwise disabled.
|
shared secret, even if [`enable_registration`](#enable_registration) is not
|
||||||
|
set.
|
||||||
|
|
||||||
|
This is primarily intended for use with the `register_new_matrix_user` script
|
||||||
|
(see [Registering a user](../../setup/installation.md#registering-a-user));
|
||||||
|
however, the interface is [documented](../admin_api/register_api.html).
|
||||||
|
|
||||||
See also [`registration_shared_secret_path`](#registration_shared_secret_path).
|
See also [`registration_shared_secret_path`](#registration_shared_secret_path).
|
||||||
|
|
||||||
@ -2379,6 +2334,79 @@ Example configuration:
|
|||||||
```yaml
|
```yaml
|
||||||
inhibit_user_in_use_error: true
|
inhibit_user_in_use_error: true
|
||||||
```
|
```
|
||||||
|
---
|
||||||
|
## User session management
|
||||||
|
---
|
||||||
|
### `session_lifetime`
|
||||||
|
|
||||||
|
Time that a user's session remains valid for, after they log in.
|
||||||
|
|
||||||
|
Note that this is not currently compatible with guest logins.
|
||||||
|
|
||||||
|
Note also that this is calculated at login time: changes are not applied retrospectively to users who have already
|
||||||
|
logged in.
|
||||||
|
|
||||||
|
By default, this is infinite.
|
||||||
|
|
||||||
|
Example configuration:
|
||||||
|
```yaml
|
||||||
|
session_lifetime: 24h
|
||||||
|
```
|
||||||
|
----
|
||||||
|
### `refresh_access_token_lifetime`
|
||||||
|
|
||||||
|
Time that an access token remains valid for, if the session is using refresh tokens.
|
||||||
|
|
||||||
|
For more information about refresh tokens, please see the [manual](user_authentication/refresh_tokens.md).
|
||||||
|
|
||||||
|
Note that this only applies to clients which advertise support for refresh tokens.
|
||||||
|
|
||||||
|
Note also that this is calculated at login time and refresh time: changes are not applied to
|
||||||
|
existing sessions until they are refreshed.
|
||||||
|
|
||||||
|
By default, this is 5 minutes.
|
||||||
|
|
||||||
|
Example configuration:
|
||||||
|
```yaml
|
||||||
|
refreshable_access_token_lifetime: 10m
|
||||||
|
```
|
||||||
|
---
|
||||||
|
### `refresh_token_lifetime: 24h`
|
||||||
|
|
||||||
|
Time that a refresh token remains valid for (provided that it is not
|
||||||
|
exchanged for another one first).
|
||||||
|
This option can be used to automatically log-out inactive sessions.
|
||||||
|
Please see the manual for more information.
|
||||||
|
|
||||||
|
Note also that this is calculated at login time and refresh time:
|
||||||
|
changes are not applied to existing sessions until they are refreshed.
|
||||||
|
|
||||||
|
By default, this is infinite.
|
||||||
|
|
||||||
|
Example configuration:
|
||||||
|
```yaml
|
||||||
|
refresh_token_lifetime: 24h
|
||||||
|
```
|
||||||
|
---
|
||||||
|
### `nonrefreshable_access_token_lifetime`
|
||||||
|
|
||||||
|
Time that an access token remains valid for, if the session is NOT
|
||||||
|
using refresh tokens.
|
||||||
|
|
||||||
|
Please note that not all clients support refresh tokens, so setting
|
||||||
|
this to a short value may be inconvenient for some users who will
|
||||||
|
then be logged out frequently.
|
||||||
|
|
||||||
|
Note also that this is calculated at login time: changes are not applied
|
||||||
|
retrospectively to existing sessions for users that have already logged in.
|
||||||
|
|
||||||
|
By default, this is infinite.
|
||||||
|
|
||||||
|
Example configuration:
|
||||||
|
```yaml
|
||||||
|
nonrefreshable_access_token_lifetime: 24h
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
## Metrics ###
|
## Metrics ###
|
||||||
Config options related to metrics.
|
Config options related to metrics.
|
||||||
@ -2666,13 +2694,10 @@ key_server_signing_keys_path: "key_server_signing_keys.key"
|
|||||||
The following settings can be used to make Synapse use a single sign-on
|
The following settings can be used to make Synapse use a single sign-on
|
||||||
provider for authentication, instead of its internal password database.
|
provider for authentication, instead of its internal password database.
|
||||||
|
|
||||||
You will probably also want to set the following options to false to
|
You will probably also want to set the following options to `false` to
|
||||||
disable the regular login/registration flows:
|
disable the regular login/registration flows:
|
||||||
* `enable_registration`
|
* [`enable_registration`](#enable_registration)
|
||||||
* `password_config.enabled`
|
* [`password_config.enabled`](#password_config)
|
||||||
|
|
||||||
You will also want to investigate the settings under the "sso" configuration
|
|
||||||
section below.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
### `saml2_config`
|
### `saml2_config`
|
||||||
|
Loading…
Reference in New Issue
Block a user