diff --git a/develop/404.html b/develop/404.html index 15eccdfea2..08762e4aa2 100644 --- a/develop/404.html +++ b/develop/404.html @@ -101,7 +101,7 @@ diff --git a/develop/CAPTCHA_SETUP.html b/develop/CAPTCHA_SETUP.html index c0e6ac0e95..44dcced760 100644 --- a/develop/CAPTCHA_SETUP.html +++ b/develop/CAPTCHA_SETUP.html @@ -99,7 +99,7 @@ diff --git a/develop/MSC1711_certificates_FAQ.html b/develop/MSC1711_certificates_FAQ.html index 0982669d01..c78a62cbe5 100644 --- a/develop/MSC1711_certificates_FAQ.html +++ b/develop/MSC1711_certificates_FAQ.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/account_validity.html b/develop/admin_api/account_validity.html index 58c9681656..8d2e0e5675 100644 --- a/develop/admin_api/account_validity.html +++ b/develop/admin_api/account_validity.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/delete_group.html b/develop/admin_api/delete_group.html index 6f894ccd55..64a94892a7 100644 --- a/develop/admin_api/delete_group.html +++ b/develop/admin_api/delete_group.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/event_reports.html b/develop/admin_api/event_reports.html index 0cad36c62b..30d526a8d1 100644 --- a/develop/admin_api/event_reports.html +++ b/develop/admin_api/event_reports.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/media_admin_api.html b/develop/admin_api/media_admin_api.html index 21a8dd3a9f..1dbcb90331 100644 --- a/develop/admin_api/media_admin_api.html +++ b/develop/admin_api/media_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/purge_history_api.html b/develop/admin_api/purge_history_api.html index 69206b5095..f8ae5868d0 100644 --- a/develop/admin_api/purge_history_api.html +++ b/develop/admin_api/purge_history_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/register_api.html b/develop/admin_api/register_api.html index f7d344f1c3..4206225eae 100644 --- a/develop/admin_api/register_api.html +++ b/develop/admin_api/register_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/room_membership.html b/develop/admin_api/room_membership.html index 7406a148b7..c16ed2e015 100644 --- a/develop/admin_api/room_membership.html +++ b/develop/admin_api/room_membership.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/rooms.html b/develop/admin_api/rooms.html index ba798260e6..b17fb730ea 100644 --- a/develop/admin_api/rooms.html +++ b/develop/admin_api/rooms.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/server_notices.html b/develop/admin_api/server_notices.html index 40abf53bd3..819e2bdb39 100644 --- a/develop/admin_api/server_notices.html +++ b/develop/admin_api/server_notices.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/statistics.html b/develop/admin_api/statistics.html index 2761c007d0..3b8e9d1667 100644 --- a/develop/admin_api/statistics.html +++ b/develop/admin_api/statistics.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/user_admin_api.html b/develop/admin_api/user_admin_api.html index 65b9cfe00e..e139a40f2b 100644 --- a/develop/admin_api/user_admin_api.html +++ b/develop/admin_api/user_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/version_api.html b/develop/admin_api/version_api.html index c31d017f76..f1f0b6b10c 100644 --- a/develop/admin_api/version_api.html +++ b/develop/admin_api/version_api.html @@ -99,7 +99,7 @@ diff --git a/develop/application_services.html b/develop/application_services.html index a163e38009..5e74670b8e 100644 --- a/develop/application_services.html +++ b/develop/application_services.html @@ -99,7 +99,7 @@ diff --git a/develop/auth_chain_difference_algorithm.html b/develop/auth_chain_difference_algorithm.html index d7205f7365..800e78745a 100644 --- a/develop/auth_chain_difference_algorithm.html +++ b/develop/auth_chain_difference_algorithm.html @@ -99,7 +99,7 @@ diff --git a/develop/code_style.html b/develop/code_style.html index 9c5c59c06e..e9cc99d016 100644 --- a/develop/code_style.html +++ b/develop/code_style.html @@ -99,7 +99,7 @@ diff --git a/develop/consent_tracking.html b/develop/consent_tracking.html index d123c3ff16..7625152c5c 100644 --- a/develop/consent_tracking.html +++ b/develop/consent_tracking.html @@ -99,7 +99,7 @@ diff --git a/develop/delegate.html b/develop/delegate.html index 797e61c36b..d809078683 100644 --- a/develop/delegate.html +++ b/develop/delegate.html @@ -99,7 +99,7 @@ diff --git a/develop/deprecation_policy.html b/develop/deprecation_policy.html index b30fd49e55..763e4a3167 100644 --- a/develop/deprecation_policy.html +++ b/develop/deprecation_policy.html @@ -99,7 +99,7 @@ diff --git a/develop/development/cas.html b/develop/development/cas.html index 821b5c72be..77ab326199 100644 --- a/develop/development/cas.html +++ b/develop/development/cas.html @@ -99,7 +99,7 @@ diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index f990ed1071..d1c5d23740 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -99,7 +99,7 @@ diff --git a/develop/development/database_schema.html b/develop/development/database_schema.html index 46a5e15c02..3f4b14529f 100644 --- a/develop/development/database_schema.html +++ b/develop/development/database_schema.html @@ -99,7 +99,7 @@ diff --git a/develop/development/experimental_features.html b/develop/development/experimental_features.html index 732ca04f10..2f43532f48 100644 --- a/develop/development/experimental_features.html +++ b/develop/development/experimental_features.html @@ -99,7 +99,7 @@ diff --git a/develop/development/git.html b/develop/development/git.html index 1a1c35f37b..0389e016cb 100644 --- a/develop/development/git.html +++ b/develop/development/git.html @@ -99,7 +99,7 @@ diff --git a/develop/development/internal_documentation/index.html b/develop/development/internal_documentation/index.html index e328539fbf..5b2735ea41 100644 --- a/develop/development/internal_documentation/index.html +++ b/develop/development/internal_documentation/index.html @@ -99,7 +99,7 @@ diff --git a/develop/development/room-dag-concepts.html b/develop/development/room-dag-concepts.html index 4c0cd0a2fd..8ffc818240 100644 --- a/develop/development/room-dag-concepts.html +++ b/develop/development/room-dag-concepts.html @@ -99,7 +99,7 @@ diff --git a/develop/development/saml.html b/develop/development/saml.html index ce1c34ad3d..8c6b2f212a 100644 --- a/develop/development/saml.html +++ b/develop/development/saml.html @@ -99,7 +99,7 @@ diff --git a/develop/development/url_previews.html b/develop/development/url_previews.html index 5ae569794c..4b3647ab59 100644 --- a/develop/development/url_previews.html +++ b/develop/development/url_previews.html @@ -99,7 +99,7 @@ diff --git a/develop/federate.html b/develop/federate.html index a42567f4c1..cd9ea73692 100644 --- a/develop/federate.html +++ b/develop/federate.html @@ -99,7 +99,7 @@ diff --git a/develop/index.html b/develop/index.html index ae12c61fee..6a2d454513 100644 --- a/develop/index.html +++ b/develop/index.html @@ -99,7 +99,7 @@ diff --git a/develop/jwt.html b/develop/jwt.html index 2d48285fd5..da2550f050 100644 --- a/develop/jwt.html +++ b/develop/jwt.html @@ -99,7 +99,7 @@ diff --git a/develop/log_contexts.html b/develop/log_contexts.html index d06ecd3779..30b8d1c53d 100644 --- a/develop/log_contexts.html +++ b/develop/log_contexts.html @@ -99,7 +99,7 @@ diff --git a/develop/manhole.html b/develop/manhole.html index f95df1aca2..c376f629ee 100644 --- a/develop/manhole.html +++ b/develop/manhole.html @@ -99,7 +99,7 @@ diff --git a/develop/media_repository.html b/develop/media_repository.html index f38aa7780c..32ca51de3c 100644 --- a/develop/media_repository.html +++ b/develop/media_repository.html @@ -99,7 +99,7 @@ diff --git a/develop/message_retention_policies.html b/develop/message_retention_policies.html index 11ed6b075c..a930b5ec1c 100644 --- a/develop/message_retention_policies.html +++ b/develop/message_retention_policies.html @@ -99,7 +99,7 @@ diff --git a/develop/metrics-howto.html b/develop/metrics-howto.html index 3b0d05638f..7b21142b1b 100644 --- a/develop/metrics-howto.html +++ b/develop/metrics-howto.html @@ -99,7 +99,7 @@ diff --git a/develop/modules/account_validity_callbacks.html b/develop/modules/account_validity_callbacks.html index 261c3d826d..e5065164c3 100644 --- a/develop/modules/account_validity_callbacks.html +++ b/develop/modules/account_validity_callbacks.html @@ -99,7 +99,7 @@ @@ -216,7 +216,7 @@ represented by their Matrix user ID.

- @@ -234,7 +234,7 @@ represented by their Matrix user ID.

- diff --git a/develop/modules/index.html b/develop/modules/index.html index 6b4a3977d8..956e84dab8 100644 --- a/develop/modules/index.html +++ b/develop/modules/index.html @@ -99,7 +99,7 @@ diff --git a/develop/modules/password_auth_provider_callbacks.html b/develop/modules/password_auth_provider_callbacks.html new file mode 100644 index 0000000000..d0762dc5a9 --- /dev/null +++ b/develop/modules/password_auth_provider_callbacks.html @@ -0,0 +1,390 @@ + + + + + + Password auth provider callbacks - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

Password auth provider callbacks

+

Password auth providers offer a way for server administrators to integrate +their Synapse installation with an external authentication system. The callbacks can be +registered by using the Module API's register_password_auth_provider_callbacks method.

+

Callbacks

+

auth_checkers

+
 auth_checkers: Dict[Tuple[str,Tuple], Callable]
+
+

A dict mapping from tuples of a login type identifier (such as m.login.password) and a +tuple of field names (such as ("password", "secret_thing")) to authentication checking +callbacks, which should be of the following form:

+
async def check_auth(
+    user: str,
+    login_type: str,
+    login_dict: "synapse.module_api.JsonDict",
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+
+

The login type and field names should be provided by the user in the +request to the /login API. The Matrix specification +defines some types, however user defined ones are also allowed.

+

The callback is passed the user field provided by the client (which might not be in +@username:server form), the login type, and a dictionary of login secrets passed by +the client.

+

If the authentication is successful, the module must return the user's Matrix ID (e.g. +@alice:example.com) and optionally a callback to be called with the response to the +/login request. If the module doesn't wish to return a callback, it must return None +instead.

+

If the authentication is unsuccessful, the module must return None.

+

check_3pid_auth

+
async def check_3pid_auth(
+    medium: str, 
+    address: str,
+    password: str,
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+
+

Called when a user attempts to register or log in with a third party identifier, +such as email. It is passed the medium (eg. email), an address (eg. jdoe@example.com) +and the user's password.

+

If the authentication is successful, the module must return the user's Matrix ID (e.g. +@alice:example.com) and optionally a callback to be called with the response to the /login request. +If the module doesn't wish to return a callback, it must return None instead.

+

If the authentication is unsuccessful, the module must return None.

+

on_logged_out

+
async def on_logged_out(
+    user_id: str,
+    device_id: Optional[str],
+    access_token: str
+) -> None
+
+

Called during a logout request for a user. It is passed the qualified user ID, the ID of the +deactivated device (if any: access tokens are occasionally created without an associated +device ID), and the (now deactivated) access token.

+

Example

+

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

+
    +
  • my.login.type +
      +
    • Expects a my_field field to be sent to /login
      • +
    • Is checked by the method: self.check_my_login
      • +
    +
    • +
  • m.login.password (defined in the spec) +
      +
    • Expects a password field to be sent to /login
      • +
    • Is checked by the method: self.check_pass
      • +
    +
    • +
+
from typing import Awaitable, Callable, Optional, Tuple
+
+import synapse
+from synapse import module_api
+
+
+class MyAuthProvider:
+    def __init__(self, config: dict, api: module_api):
+
+        self.api = api
+
+        self.credentials = {
+            "bob": "building",
+            "@scoop:matrix.org": "digging",
+        }
+
+        api.register_password_auth_provider_callbacks(
+            auth_checkers={
+                ("my.login_type", ("my_field",)): self.check_my_login,
+                ("m.login.password", ("password",)): self.check_pass,
+            },
+        )
+
+    async def check_my_login(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "my.login_type":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("my_field"):
+            return self.api.get_qualified_user_id(username)
+
+    async def check_pass(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "m.login.password":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("password"):
+            return self.api.get_qualified_user_id(username)
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/develop/modules/porting_legacy_module.html b/develop/modules/porting_legacy_module.html index b03f0e3aec..e831655ea5 100644 --- a/develop/modules/porting_legacy_module.html +++ b/develop/modules/porting_legacy_module.html @@ -99,7 +99,7 @@ @@ -194,6 +194,8 @@ for more info). should register this resource in its __init__ method using the register_web_resource method from the ModuleApi class (see this section for more info).

+

There is no longer a get_db_schema_files callback provided for password auth provider modules. Any +changes to the database should now be made by the module using the module API class.

The module's author should also update any example in the module's configuration to only use the new modules section in Synapse's configuration file (see this section for more info).

@@ -203,7 +205,7 @@ for more info).