diff options
author | richvdh <richvdh@users.noreply.github.com> | 2022-08-26 13:30:09 +0000 |
---|---|---|
committer | richvdh <richvdh@users.noreply.github.com> | 2022-08-26 13:30:09 +0000 |
commit | 87e4857eec7ec47a1780e10d1ac8bbe5e9210af9 (patch) | |
tree | 4f9fbaaab4080b329fa87cb96b71c375911d287e /develop/print.html | |
parent | deploy: 5e5c8150d798f6929ddedbb39f9f11486558cdbc (diff) | |
download | synapse-87e4857eec7ec47a1780e10d1ac8bbe5e9210af9.tar.xz |
deploy: c4e29b6908ac8ae57b5e9a3e7662ad638b61e94a
Diffstat (limited to 'develop/print.html')
-rw-r--r-- | develop/print.html | 180 |
1 files changed, 101 insertions, 79 deletions
diff --git a/develop/print.html b/develop/print.html index 5e6d6b2b81..d047ae9fa3 100644 --- a/develop/print.html +++ b/develop/print.html @@ -583,8 +583,12 @@ and <code>notif_from</code> fields filled out. You may also need to set <code>s <p>If email is not configured, password reset, registration and notifications via email will be disabled.</p> <h3 id="registering-a-user"><a class="header" href="#registering-a-user">Registering a user</a></h3> -<p>The easiest way to create a new user is to do so from a client like <a href="https://element.io/">Element</a>.</p> -<p>Alternatively, you can do so from the command line. This can be done as follows:</p> +<p>One way to create a new user is to do so from a client like +<a href="https://element.io/">Element</a>. This requires registration to be enabled via +the +<a href="setup/../usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> +setting.</p> +<p>Alternatively, you can create new users from the command line. This can be done as follows:</p> <ol> <li>If synapse was installed via pip, activate the virtualenv as follows (if Synapse was installed via a prebuilt package, <code>register_new_matrix_user</code> should already be @@ -595,7 +599,7 @@ synctl start # if not already running </code></pre> </li> <li>Run the following command: -<pre><code class="language-sh">register_new_matrix_user -c homeserver.yaml http://localhost:8008 +<pre><code class="language-sh">register_new_matrix_user -c homeserver.yaml </code></pre> </li> </ol> @@ -607,12 +611,13 @@ Confirm password: Make admin [no]: Success! </code></pre> -<p>This process uses a setting <code>registration_shared_secret</code> in -<code>homeserver.yaml</code>, which is shared between Synapse itself and the -<code>register_new_matrix_user</code> script. It doesn't matter what it is (a random -value is generated by <code>--generate-config</code>), but it should be kept secret, as -anyone with knowledge of it can register users, including admin accounts, -on your server even if <code>enable_registration</code> is <code>false</code>.</p> +<p>This process uses a setting +<a href="setup/../usage/configuration/config_documentation.html#registration_shared_secret"><code>registration_shared_secret</code></a>, +which is shared between Synapse itself and the <code>register_new_matrix_user</code> +script. It doesn't matter what it is (a random value is generated by +<code>--generate-config</code>), but it should be kept secret, as anyone with knowledge of +it can register users, including admin accounts, on your server even if +<code>enable_registration</code> is <code>false</code>.</p> <h3 id="setting-up-a-turn-server"><a class="header" href="#setting-up-a-turn-server">Setting up a TURN server</a></h3> <p>For reliable VoIP calls to be routed via this homeserver, you MUST configure a TURN server. See <a href="setup/../turn-howto.html">TURN setup</a> for details.</p> @@ -4728,23 +4733,25 @@ should be in the form of providers.json). By default this list is empty.</p> <p>See <a href="usage/configuration/../../CAPTCHA_SETUP.html">here</a> for full details on setting up captcha.</p> <hr /> <h3 id="recaptcha_public_key"><a class="header" href="#recaptcha_public_key"><code>recaptcha_public_key</code></a></h3> -<p>This homeserver's ReCAPTCHA public key. Must be specified if <code>enable_registration_captcha</code> is -enabled.</p> +<p>This homeserver's ReCAPTCHA public key. Must be specified if +<a href="usage/configuration/config_documentation.html#enable_registration_captcha"><code>enable_registration_captcha</code></a> is enabled.</p> <p>Example configuration:</p> <pre><code class="language-yaml">recaptcha_public_key: "YOUR_PUBLIC_KEY" </code></pre> <hr /> <h3 id="recaptcha_private_key"><a class="header" href="#recaptcha_private_key"><code>recaptcha_private_key</code></a></h3> -<p>This homeserver's ReCAPTCHA private key. Must be specified if <code>enable_registration_captcha</code> is +<p>This homeserver's ReCAPTCHA private key. Must be specified if +<a href="usage/configuration/config_documentation.html#enable_registration_captcha"><code>enable_registration_captcha</code></a> is enabled.</p> <p>Example configuration:</p> <pre><code class="language-yaml">recaptcha_private_key: "YOUR_PRIVATE_KEY" </code></pre> <hr /> <h3 id="enable_registration_captcha"><a class="header" href="#enable_registration_captcha"><code>enable_registration_captcha</code></a></h3> -<p>Set to true to enable ReCaptcha checks when registering, preventing signup -unless a captcha is answered. Requires a valid ReCaptcha public/private key. -Defaults to false.</p> +<p>Set to <code>true</code> to require users to complete a CAPTCHA test when registering an account. +Requires a valid ReCaptcha public/private key. +Defaults to <code>false</code>.</p> +<p>Note that <a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> must also be set to allow account registration.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_registration_captcha: true </code></pre> @@ -4796,69 +4803,34 @@ it allows users to connect to arbitrary endpoints without having first signed up <p>Registration can be rate-limited using the parameters in the <a href="usage/configuration/config_documentation.html#ratelimiting">Ratelimiting</a> section of this manual.</p> <hr /> <h3 id="enable_registration"><a class="header" href="#enable_registration"><code>enable_registration</code></a></h3> -<p>Enable registration for new users. Defaults to false. It is highly recommended that if you enable registration, -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 <code>enable_registration_without_verification</code> to true.</p> +<p>Enable registration for new users. Defaults to <code>false</code>.</p> +<p>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":</p> +<ul> +<li><a href="usage/configuration/config_documentation.html#enable_registration_captcha"><code>enable_registration_captcha</code></a></li> +<li><a href="usage/configuration/config_documentation.html#registrations_require_3pid"><code>registrations_require_3pid</code></a></li> +<li><a href="usage/configuration/config_documentation.html#registration_requires_token"><code>registration_requires_token</code></a></li> +</ul> +<p>(In order to enable registration without any verification, you must also set +<a href="usage/configuration/config_documentation.html#enable_registration_without_verification"><code>enable_registration_without_verification</code></a>.)</p> +<p>Note that even if this setting is disabled, new accounts can still be created +via the admin API if +<a href="usage/configuration/config_documentation.html#registration_shared_secret"><code>registration_shared_secret</code></a> is set.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_registration: true </code></pre> <hr /> <h3 id="enable_registration_without_verification"><a class="header" href="#enable_registration_without_verification"><code>enable_registration_without_verification</code></a></h3> <p>Enable registration without email or captcha verification. Note: this option is <em>not</em> recommended, -as registration without verification is a known vector for spam and abuse. Defaults to false. Has no effect -unless <code>enable_registration</code> is also enabled.</p> +as registration without verification is a known vector for spam and abuse. Defaults to <code>false</code>. Has no effect +unless <a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> is also enabled.</p> <p>Example configuration:</p> <pre><code class="language-yaml">enable_registration_without_verification: true </code></pre> <hr /> -<h3 id="session_lifetime"><a class="header" href="#session_lifetime"><code>session_lifetime</code></a></h3> -<p>Time that a user's session remains valid for, after they log in.</p> -<p>Note that this is not currently compatible with guest logins.</p> -<p>Note also that this is calculated at login time: changes are not applied retrospectively to users who have already -logged in.</p> -<p>By default, this is infinite.</p> -<p>Example configuration:</p> -<pre><code class="language-yaml">session_lifetime: 24h -</code></pre> -<hr /> -<h3 id="refresh_access_token_lifetime"><a class="header" href="#refresh_access_token_lifetime"><code>refresh_access_token_lifetime</code></a></h3> -<p>Time that an access token remains valid for, if the session is using refresh tokens.</p> -<p>For more information about refresh tokens, please see the <a href="usage/configuration/user_authentication/refresh_tokens.html">manual</a>.</p> -<p>Note that this only applies to clients which advertise support for refresh tokens.</p> -<p>Note also that this is calculated at login time and refresh time: changes are not applied to -existing sessions until they are refreshed.</p> -<p>By default, this is 5 minutes.</p> -<p>Example configuration:</p> -<pre><code class="language-yaml">refreshable_access_token_lifetime: 10m -</code></pre> -<hr /> -<h3 id="refresh_token_lifetime-24h"><a class="header" href="#refresh_token_lifetime-24h"><code>refresh_token_lifetime: 24h</code></a></h3> -<p>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.</p> -<p>Note also that this is calculated at login time and refresh time: -changes are not applied to existing sessions until they are refreshed.</p> -<p>By default, this is infinite.</p> -<p>Example configuration:</p> -<pre><code class="language-yaml">refresh_token_lifetime: 24h -</code></pre> -<hr /> -<h3 id="nonrefreshable_access_token_lifetime"><a class="header" href="#nonrefreshable_access_token_lifetime"><code>nonrefreshable_access_token_lifetime</code></a></h3> -<p>Time that an access token remains valid for, if the session is NOT -using refresh tokens.</p> -<p>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.</p> -<p>Note also that this is calculated at login time: changes are not applied -retrospectively to existing sessions for users that have already logged in.</p> -<p>By default, this is infinite.</p> -<p>Example configuration:</p> -<pre><code class="language-yaml">nonrefreshable_access_token_lifetime: 24h -</code></pre> -<hr /> <h3 id="registrations_require_3pid"><a class="header" href="#registrations_require_3pid"><code>registrations_require_3pid</code></a></h3> -<p>If this is set, the user must provide all of the specified types of 3PID when registering.</p> +<p>If this is set, users must provide all of the specified types of 3PID when registering an account.</p> +<p>Note that <a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> must also be set to allow account registration.</p> <p>Example configuration:</p> <pre><code class="language-yaml">registrations_require_3pid: - email @@ -4894,16 +4866,20 @@ flow (overrides <code>registrations_require_3pid</code> if MSISDNs are set as re <h3 id="registration_requires_token"><a class="header" href="#registration_requires_token"><code>registration_requires_token</code></a></h3> <p>Require users to submit a token during registration. Tokens can be managed using the admin <a href="usage/configuration/../administration/admin_api/registration_tokens.html">API</a>. -Note that <code>enable_registration</code> must be set to true. Disabling this option will not delete any tokens previously generated. -Defaults to false. Set to true to enable.</p> +Defaults to <code>false</code>. Set to <code>true</code> to enable.</p> +<p>Note that <a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> must also be set to allow account registration.</p> <p>Example configuration:</p> <pre><code class="language-yaml">registration_requires_token: true </code></pre> <hr /> <h3 id="registration_shared_secret"><a class="header" href="#registration_shared_secret"><code>registration_shared_secret</code></a></h3> -<p>If set, allows registration of standard or admin accounts by anyone who -has the shared secret, even if registration is otherwise disabled.</p> +<p>If set, allows registration of standard or admin accounts by anyone who has the +shared secret, even if <a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a> is not +set.</p> +<p>This is primarily intended for use with the <code>register_new_matrix_user</code> script +(see <a href="usage/configuration/../../setup/installation.html#registering-a-user">Registering a user</a>); +however, the interface is <a href="usage/configuration/../admin_api/register_api.html">documented</a>.</p> <p>See also <a href="usage/configuration/config_documentation.html#registration_shared_secret_path"><code>registration_shared_secret_path</code></a>.</p> <p>Example configuration:</p> <pre><code class="language-yaml">registration_shared_secret: <PRIVATE STRING> @@ -5087,6 +5063,54 @@ raise an error if the registration completes and the username conflicts.</p> <pre><code class="language-yaml">inhibit_user_in_use_error: true </code></pre> <hr /> +<h2 id="user-session-management"><a class="header" href="#user-session-management">User session management</a></h2> +<hr /> +<h3 id="session_lifetime"><a class="header" href="#session_lifetime"><code>session_lifetime</code></a></h3> +<p>Time that a user's session remains valid for, after they log in.</p> +<p>Note that this is not currently compatible with guest logins.</p> +<p>Note also that this is calculated at login time: changes are not applied retrospectively to users who have already +logged in.</p> +<p>By default, this is infinite.</p> +<p>Example configuration:</p> +<pre><code class="language-yaml">session_lifetime: 24h +</code></pre> +<hr /> +<h3 id="refresh_access_token_lifetime"><a class="header" href="#refresh_access_token_lifetime"><code>refresh_access_token_lifetime</code></a></h3> +<p>Time that an access token remains valid for, if the session is using refresh tokens.</p> +<p>For more information about refresh tokens, please see the <a href="usage/configuration/user_authentication/refresh_tokens.html">manual</a>.</p> +<p>Note that this only applies to clients which advertise support for refresh tokens.</p> +<p>Note also that this is calculated at login time and refresh time: changes are not applied to +existing sessions until they are refreshed.</p> +<p>By default, this is 5 minutes.</p> +<p>Example configuration:</p> +<pre><code class="language-yaml">refreshable_access_token_lifetime: 10m +</code></pre> +<hr /> +<h3 id="refresh_token_lifetime-24h"><a class="header" href="#refresh_token_lifetime-24h"><code>refresh_token_lifetime: 24h</code></a></h3> +<p>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.</p> +<p>Note also that this is calculated at login time and refresh time: +changes are not applied to existing sessions until they are refreshed.</p> +<p>By default, this is infinite.</p> +<p>Example configuration:</p> +<pre><code class="language-yaml">refresh_token_lifetime: 24h +</code></pre> +<hr /> +<h3 id="nonrefreshable_access_token_lifetime"><a class="header" href="#nonrefreshable_access_token_lifetime"><code>nonrefreshable_access_token_lifetime</code></a></h3> +<p>Time that an access token remains valid for, if the session is NOT +using refresh tokens.</p> +<p>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.</p> +<p>Note also that this is calculated at login time: changes are not applied +retrospectively to existing sessions for users that have already logged in.</p> +<p>By default, this is infinite.</p> +<p>Example configuration:</p> +<pre><code class="language-yaml">nonrefreshable_access_token_lifetime: 24h +</code></pre> +<hr /> <h2 id="metrics"><a class="header" href="#metrics">Metrics</a></h2> <p>Config options related to metrics.</p> <hr /> @@ -5310,14 +5334,12 @@ defaults to the server signing key.</p> <h2 id="single-sign-on-integration"><a class="header" href="#single-sign-on-integration">Single sign-on integration</a></h2> <p>The following settings can be used to make Synapse use a single sign-on provider for authentication, instead of its internal password database.</p> -<p>You will probably also want to set the following options to false to +<p>You will probably also want to set the following options to <code>false</code> to disable the regular login/registration flows:</p> <ul> -<li><code>enable_registration</code></li> -<li><code>password_config.enabled</code></li> +<li><a href="usage/configuration/config_documentation.html#enable_registration"><code>enable_registration</code></a></li> +<li><a href="usage/configuration/config_documentation.html#password_config"><code>password_config.enabled</code></a></li> </ul> -<p>You will also want to investigate the settings under the "sso" configuration -section below.</p> <hr /> <h3 id="saml2_config"><a class="header" href="#saml2_config"><code>saml2_config</code></a></h3> <p>Enable SAML2 for registration and login. Uses pysaml2. To learn more about pysaml and @@ -10855,9 +10877,9 @@ a purge id:</p> non-interactive way. This is generally used for bootstrapping a Synapse instance with administrator accounts.</p> <p>To authenticate yourself to the server, you will need both the shared secret -(<code>registration_shared_secret</code> in the homeserver configuration), and a -one-time nonce. If the registration shared secret is not configured, this API -is not enabled.</p> +(<a href="admin_api/../configuration/config_documentation.html#registration_shared_secret"><code>registration_shared_secret</code></a> +in the homeserver configuration), and a one-time nonce. If the registration +shared secret is not configured, this API is not enabled.</p> <p>To fetch the nonce, you need to request one from the API:</p> <pre><code>> GET /_synapse/admin/v1/register |