deploy: 2d3bd9aa670eedd299cc03093459929adec41918

1 files changed, 49 insertions, 0 deletions

diff --git a/develop/modules/password_auth_provider_callbacks.html b/develop/modules/password_auth_provider_callbacks.html
index b68ee18177..0ff2e3ea6d 100644
--- a/develop/modules/password_auth_provider_callbacks.html
+++ b/develop/modules/password_auth_provider_callbacks.html
@@ -260,6 +260,55 @@ the authentication is denied.</p>
 deactivated device (if any: access tokens are occasionally created without an associated
 device ID), and the (now deactivated) access token.</p>
 <p>If multiple modules implement this callback, Synapse runs them all in order.</p>
+<h3 id="get_username_for_registration"><a class="header" href="#get_username_for_registration"><code>get_username_for_registration</code></a></h3>
+<p><em>First introduced in Synapse v1.52.0</em></p>
+<pre><code class="language-python">async def get_username_for_registration(
+    uia_results: Dict[str, Any],
+    params: Dict[str, Any],
+) -&gt; Optional[str]
+</code></pre>
+<p>Called when registering a new user. The module can return a username to set for the user
+being registered by returning it as a string, or <code>None</code> if it doesn't wish to force a
+username for this user. If a username is returned, it will be used as the local part of a
+user's full Matrix ID (e.g. it's <code>alice</code> in <code>@alice:example.com</code>).</p>
+<p>This callback is called once <a href="https://spec.matrix.org/latest/client-server-api/#user-interactive-authentication-api">User-Interactive Authentication</a>
+has been completed by the user. It is not called when registering a user via SSO. It is
+passed two dictionaries, which include the information that the user has provided during
+the registration process.</p>
+<p>The first dictionary contains the results of the <a href="https://spec.matrix.org/latest/client-server-api/#user-interactive-authentication-api">User-Interactive Authentication</a>
+flow followed by the user. Its keys are the identifiers of every step involved in the flow,
+associated with either a boolean value indicating whether the step was correctly completed,
+or additional information (e.g. email address, phone number...). A list of most existing
+identifiers can be found in the <a href="https://spec.matrix.org/v1.1/client-server-api/#authentication-types">Matrix specification</a>.
+Here's an example featuring all currently supported keys:</p>
+<pre><code class="language-python">{
+    &quot;m.login.dummy&quot;: True,  # Dummy authentication
+    &quot;m.login.terms&quot;: True,  # User has accepted the terms of service for the homeserver
+    &quot;m.login.recaptcha&quot;: True,  # User has completed the recaptcha challenge
+    &quot;m.login.email.identity&quot;: {  # User has provided and verified an email address
+        &quot;medium&quot;: &quot;email&quot;,
+        &quot;address&quot;: &quot;alice@example.com&quot;,
+        &quot;validated_at&quot;: 1642701357084,
+    },
+    &quot;m.login.msisdn&quot;: {  # User has provided and verified a phone number
+        &quot;medium&quot;: &quot;msisdn&quot;,
+        &quot;address&quot;: &quot;33123456789&quot;,
+        &quot;validated_at&quot;: 1642701357084,
+    },
+    &quot;org.matrix.msc3231.login.registration_token&quot;: &quot;sometoken&quot;,  # User has registered through the flow described in MSC3231
+}
+</code></pre>
+<p>The second dictionary contains the parameters provided by the user's client in the request
+to <code>/_matrix/client/v3/register</code>. See the <a href="https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3register">Matrix specification</a>
+for a complete list of these parameters.</p>
+<p>If the module cannot, or does not wish to, generate a username for this user, it must
+return <code>None</code>.</p>
+<p>If multiple modules implement this callback, they will be considered in order. If a
+callback returns <code>None</code>, Synapse falls through to the next one. The value of the first
+callback that does not return <code>None</code> will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback. If every callback return <code>None</code>,
+the username provided by the user is used, if any (otherwise one is automatically
+generated).</p>
 <h2 id="example"><a class="header" href="#example">Example</a></h2>
 <p>The example module below implements authentication checkers for two different login types: </p>
 <ul>