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.

deactivated device (if any: access tokens are occasionally created without an associated device ID), and the (now deactivated) access token.

If multiple modules implement this callback, Synapse runs them all in order.

+

get_username_for_registration

+

First introduced in Synapse v1.52.0

+
async def get_username_for_registration(
+    uia_results: Dict[str, Any],
+    params: Dict[str, Any],
+) -> Optional[str]
+
+

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 None 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 alice in @alice:example.com).

+

This callback is called once User-Interactive Authentication +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.

+

The first dictionary contains the results of the User-Interactive Authentication +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 Matrix specification. +Here's an example featuring all currently supported keys:

+
{
+    "m.login.dummy": True,  # Dummy authentication
+    "m.login.terms": True,  # User has accepted the terms of service for the homeserver
+    "m.login.recaptcha": True,  # User has completed the recaptcha challenge
+    "m.login.email.identity": {  # User has provided and verified an email address
+        "medium": "email",
+        "address": "alice@example.com",
+        "validated_at": 1642701357084,
+    },
+    "m.login.msisdn": {  # User has provided and verified a phone number
+        "medium": "msisdn",
+        "address": "33123456789",
+        "validated_at": 1642701357084,
+    },
+    "org.matrix.msc3231.login.registration_token": "sometoken",  # User has registered through the flow described in MSC3231
+}
+
+

The second dictionary contains the parameters provided by the user's client in the request +to /_matrix/client/v3/register. See the Matrix specification +for a complete list of these parameters.

+

If the module cannot, or does not wish to, generate a username for this user, it must +return None.

+

If multiple modules implement this callback, they will be considered in order. If a +callback returns None, Synapse falls through to the next one. The value of the first +callback that does not return None will be used. If this happens, Synapse will not call +any of the subsequent implementations of this callback. If every callback return None, +the username provided by the user is used, if any (otherwise one is automatically +generated).

Example

The example module below implements authentication checkers for two different login types: