summary refs log tree commit diff
path: root/develop/print.html
diff options
context:
space:
mode:
authorrichvdh <richvdh@users.noreply.github.com>2022-08-26 13:30:09 +0000
committerrichvdh <richvdh@users.noreply.github.com>2022-08-26 13:30:09 +0000
commit87e4857eec7ec47a1780e10d1ac8bbe5e9210af9 (patch)
tree4f9fbaaab4080b329fa87cb96b71c375911d287e /develop/print.html
parentdeploy: 5e5c8150d798f6929ddedbb39f9f11486558cdbc (diff)
downloadsynapse-87e4857eec7ec47a1780e10d1ac8bbe5e9210af9.tar.xz
deploy: c4e29b6908ac8ae57b5e9a3e7662ad638b61e94a
Diffstat (limited to 'develop/print.html')
-rw-r--r--develop/print.html180
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: &quot;YOUR_PUBLIC_KEY&quot;
 </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: &quot;YOUR_PRIVATE_KEY&quot;
 </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 &quot;bots&quot;:</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: &lt;PRIVATE STRING&gt;
@@ -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 &quot;sso&quot; 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>&gt; GET /_synapse/admin/v1/register