From 74b65bfc5f3c58005e3892b314e73cfde32355f6 Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Tue, 2 Nov 2021 14:27:50 +0000 Subject: deploy: 2d44ee6868805d4ff23489a8dd6b4072ff358663 --- latest/404.html | 2 +- latest/CAPTCHA_SETUP.html | 2 +- latest/MSC1711_certificates_FAQ.html | 2 +- latest/admin_api/account_validity.html | 2 +- latest/admin_api/delete_group.html | 2 +- latest/admin_api/event_reports.html | 2 +- latest/admin_api/media_admin_api.html | 8 +- latest/admin_api/purge_history_api.html | 2 +- latest/admin_api/register_api.html | 2 +- latest/admin_api/room_membership.html | 2 +- latest/admin_api/rooms.html | 2 +- latest/admin_api/server_notices.html | 2 +- latest/admin_api/statistics.html | 2 +- latest/admin_api/user_admin_api.html | 22 +- latest/admin_api/version_api.html | 2 +- latest/application_services.html | 2 +- latest/auth_chain_difference_algorithm.html | 2 +- latest/code_style.html | 2 +- latest/consent_tracking.html | 2 +- latest/delegate.html | 2 +- latest/deprecation_policy.html | 2 +- latest/development/cas.html | 2 +- latest/development/contributing_guide.html | 2 +- latest/development/database_schema.html | 2 +- latest/development/experimental_features.html | 2 +- latest/development/git.html | 2 +- .../development/internal_documentation/index.html | 2 +- latest/development/room-dag-concepts.html | 2 +- latest/development/saml.html | 2 +- latest/development/url_previews.html | 2 +- latest/federate.html | 2 +- latest/index.html | 2 +- latest/jwt.html | 2 +- latest/log_contexts.html | 2 +- latest/manhole.html | 2 +- latest/media_repository.html | 2 +- latest/message_retention_policies.html | 2 +- latest/metrics-howto.html | 2 +- latest/modules/account_validity_callbacks.html | 13 +- latest/modules/index.html | 32 +- .../modules/password_auth_provider_callbacks.html | 406 ++++++++++++++++ latest/modules/porting_legacy_module.html | 8 +- latest/modules/presence_router_callbacks.html | 12 +- latest/modules/spam_checker_callbacks.html | 58 ++- latest/modules/third_party_rules_callbacks.html | 23 +- latest/modules/writing_a_module.html | 13 +- latest/openid.html | 2 +- latest/opentracing.html | 2 +- latest/password_auth_providers.html | 9 +- latest/postgres.html | 2 +- latest/print.html | 514 ++++++++++++++++----- latest/replication.html | 2 +- latest/reverse_proxy.html | 2 +- latest/room_and_user_statistics.html | 2 +- latest/sample_config.yaml | 111 ++--- latest/searchindex.js | 2 +- latest/searchindex.json | 2 +- latest/server_notices.html | 2 +- latest/setup/forward_proxy.html | 2 +- latest/setup/installation.html | 2 +- latest/sso_mapping_providers.html | 2 +- latest/structured_logging.html | 2 +- latest/synctl_workers.html | 2 +- latest/systemd-with-workers/index.html | 2 +- latest/tcp_replication.html | 2 +- latest/templates.html | 2 +- latest/turn-howto.html | 2 +- latest/upgrade.html | 66 +-- latest/usage/administration/admin_api/index.html | 2 +- .../admin_api/registration_tokens.html | 4 +- latest/usage/administration/index.html | 2 +- latest/usage/administration/request_log.html | 2 +- .../configuration/homeserver_sample_config.html | 113 ++--- latest/usage/configuration/index.html | 2 +- .../usage/configuration/logging_sample_config.html | 12 +- .../configuration/user_authentication/index.html | 2 +- latest/user_directory.html | 2 +- latest/welcome_and_overview.html | 2 +- latest/workers.html | 2 +- 79 files changed, 1156 insertions(+), 392 deletions(-) create mode 100644 latest/modules/password_auth_provider_callbacks.html diff --git a/latest/404.html b/latest/404.html index 15eccdfea2..08762e4aa2 100644 --- a/latest/404.html +++ b/latest/404.html @@ -101,7 +101,7 @@ diff --git a/latest/CAPTCHA_SETUP.html b/latest/CAPTCHA_SETUP.html index c0e6ac0e95..44dcced760 100644 --- a/latest/CAPTCHA_SETUP.html +++ b/latest/CAPTCHA_SETUP.html @@ -99,7 +99,7 @@ diff --git a/latest/MSC1711_certificates_FAQ.html b/latest/MSC1711_certificates_FAQ.html index 0982669d01..c78a62cbe5 100644 --- a/latest/MSC1711_certificates_FAQ.html +++ b/latest/MSC1711_certificates_FAQ.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/account_validity.html b/latest/admin_api/account_validity.html index 58c9681656..8d2e0e5675 100644 --- a/latest/admin_api/account_validity.html +++ b/latest/admin_api/account_validity.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/delete_group.html b/latest/admin_api/delete_group.html index 6f894ccd55..64a94892a7 100644 --- a/latest/admin_api/delete_group.html +++ b/latest/admin_api/delete_group.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/event_reports.html b/latest/admin_api/event_reports.html index 0cad36c62b..30d526a8d1 100644 --- a/latest/admin_api/event_reports.html +++ b/latest/admin_api/event_reports.html @@ -99,7 +99,7 @@ diff --git a/latest/admin_api/media_admin_api.html b/latest/admin_api/media_admin_api.html index 21a8dd3a9f..9bb617d322 100644 --- a/latest/admin_api/media_admin_api.html +++ b/latest/admin_api/media_admin_api.html @@ -99,7 +99,7 @@ @@ -371,9 +371,9 @@ See also Purge Remote Media API.

URL Parameters

If the user already exists then optional parameters default to the current value.

In order to re-activate an account deactivated must be set to false. If @@ -494,6 +499,7 @@ An empty body may be passed for backwards compatibility.

  • Remove all 3PIDs from the homeserver
  • Delete all devices and E2EE keys
  • Delete all access tokens
    • +
  • Delete all pushers
  • Delete the password hash
  • Removal from all rooms the user is a member of
  • Remove the user from the user directory
    • @@ -507,6 +513,16 @@ is set to true:

  • Remove the user's avatar URL
  • Mark the user as erased
    • +

    The following actions are NOT performed. The list may be incomplete.

    +

    Reset password

    Changes the password of another user. This will automatically log the user out of all their devices.

    The api is:

    diff --git a/latest/admin_api/version_api.html b/latest/admin_api/version_api.html index c31d017f76..f1f0b6b10c 100644 --- a/latest/admin_api/version_api.html +++ b/latest/admin_api/version_api.html @@ -99,7 +99,7 @@ diff --git a/latest/application_services.html b/latest/application_services.html index a163e38009..5e74670b8e 100644 --- a/latest/application_services.html +++ b/latest/application_services.html @@ -99,7 +99,7 @@ diff --git a/latest/auth_chain_difference_algorithm.html b/latest/auth_chain_difference_algorithm.html index d7205f7365..800e78745a 100644 --- a/latest/auth_chain_difference_algorithm.html +++ b/latest/auth_chain_difference_algorithm.html @@ -99,7 +99,7 @@ diff --git a/latest/code_style.html b/latest/code_style.html index 9c5c59c06e..e9cc99d016 100644 --- a/latest/code_style.html +++ b/latest/code_style.html @@ -99,7 +99,7 @@ diff --git a/latest/consent_tracking.html b/latest/consent_tracking.html index d123c3ff16..7625152c5c 100644 --- a/latest/consent_tracking.html +++ b/latest/consent_tracking.html @@ -99,7 +99,7 @@ diff --git a/latest/delegate.html b/latest/delegate.html index 797e61c36b..d809078683 100644 --- a/latest/delegate.html +++ b/latest/delegate.html @@ -99,7 +99,7 @@ diff --git a/latest/deprecation_policy.html b/latest/deprecation_policy.html index b30fd49e55..763e4a3167 100644 --- a/latest/deprecation_policy.html +++ b/latest/deprecation_policy.html @@ -99,7 +99,7 @@ diff --git a/latest/development/cas.html b/latest/development/cas.html index 821b5c72be..77ab326199 100644 --- a/latest/development/cas.html +++ b/latest/development/cas.html @@ -99,7 +99,7 @@ diff --git a/latest/development/contributing_guide.html b/latest/development/contributing_guide.html index f990ed1071..d1c5d23740 100644 --- a/latest/development/contributing_guide.html +++ b/latest/development/contributing_guide.html @@ -99,7 +99,7 @@ diff --git a/latest/development/database_schema.html b/latest/development/database_schema.html index 46a5e15c02..3f4b14529f 100644 --- a/latest/development/database_schema.html +++ b/latest/development/database_schema.html @@ -99,7 +99,7 @@ diff --git a/latest/development/experimental_features.html b/latest/development/experimental_features.html index 732ca04f10..2f43532f48 100644 --- a/latest/development/experimental_features.html +++ b/latest/development/experimental_features.html @@ -99,7 +99,7 @@ diff --git a/latest/development/git.html b/latest/development/git.html index 1a1c35f37b..0389e016cb 100644 --- a/latest/development/git.html +++ b/latest/development/git.html @@ -99,7 +99,7 @@ diff --git a/latest/development/internal_documentation/index.html b/latest/development/internal_documentation/index.html index e328539fbf..5b2735ea41 100644 --- a/latest/development/internal_documentation/index.html +++ b/latest/development/internal_documentation/index.html @@ -99,7 +99,7 @@ diff --git a/latest/development/room-dag-concepts.html b/latest/development/room-dag-concepts.html index 4c0cd0a2fd..8ffc818240 100644 --- a/latest/development/room-dag-concepts.html +++ b/latest/development/room-dag-concepts.html @@ -99,7 +99,7 @@ diff --git a/latest/development/saml.html b/latest/development/saml.html index ce1c34ad3d..8c6b2f212a 100644 --- a/latest/development/saml.html +++ b/latest/development/saml.html @@ -99,7 +99,7 @@ diff --git a/latest/development/url_previews.html b/latest/development/url_previews.html index 5ae569794c..4b3647ab59 100644 --- a/latest/development/url_previews.html +++ b/latest/development/url_previews.html @@ -99,7 +99,7 @@ diff --git a/latest/federate.html b/latest/federate.html index a42567f4c1..cd9ea73692 100644 --- a/latest/federate.html +++ b/latest/federate.html @@ -99,7 +99,7 @@ diff --git a/latest/index.html b/latest/index.html index ae12c61fee..6a2d454513 100644 --- a/latest/index.html +++ b/latest/index.html @@ -99,7 +99,7 @@ diff --git a/latest/jwt.html b/latest/jwt.html index 2d48285fd5..da2550f050 100644 --- a/latest/jwt.html +++ b/latest/jwt.html @@ -99,7 +99,7 @@ diff --git a/latest/log_contexts.html b/latest/log_contexts.html index d06ecd3779..30b8d1c53d 100644 --- a/latest/log_contexts.html +++ b/latest/log_contexts.html @@ -99,7 +99,7 @@ diff --git a/latest/manhole.html b/latest/manhole.html index f95df1aca2..c376f629ee 100644 --- a/latest/manhole.html +++ b/latest/manhole.html @@ -99,7 +99,7 @@ diff --git a/latest/media_repository.html b/latest/media_repository.html index f38aa7780c..32ca51de3c 100644 --- a/latest/media_repository.html +++ b/latest/media_repository.html @@ -99,7 +99,7 @@ diff --git a/latest/message_retention_policies.html b/latest/message_retention_policies.html index 11ed6b075c..a930b5ec1c 100644 --- a/latest/message_retention_policies.html +++ b/latest/message_retention_policies.html @@ -99,7 +99,7 @@ diff --git a/latest/metrics-howto.html b/latest/metrics-howto.html index 3b0d05638f..7b21142b1b 100644 --- a/latest/metrics-howto.html +++ b/latest/metrics-howto.html @@ -99,7 +99,7 @@ diff --git a/latest/modules/account_validity_callbacks.html b/latest/modules/account_validity_callbacks.html index 261c3d826d..0eabf60bb7 100644 --- a/latest/modules/account_validity_callbacks.html +++ b/latest/modules/account_validity_callbacks.html @@ -99,7 +99,7 @@ @@ -189,6 +189,7 @@ Synapse instance. Account validity callbacks can be registered using the module register_account_validity_callbacks method.

    The available account validity callbacks are:

    is_user_expired

    +

    First introduced in Synapse v1.39.0

    async def is_user_expired(user: str) -> Optional[bool]

    Called when processing any authenticated request (except for logout requests). The module @@ -198,12 +199,18 @@ represented by their Matrix user ID (e.g. @alice:example.com).

    If the module returns True, the current request will be denied with the error code ORG_MATRIX_EXPIRED_ACCOUNT and the HTTP status code 403. Note that this doesn't invalidate the user's access token.

    +

    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.

    on_user_registration

    +

    First introduced in Synapse v1.39.0

    async def on_user_registration(user: str) -> None

    Called after successfully registering a user, in case the module needs to perform extra operations to keep track of them. (e.g. add them to a database table). The user is represented by their Matrix user ID.

    +

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

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

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

    - diff --git a/latest/modules/index.html b/latest/modules/index.html index 6b4a3977d8..a512784333 100644 --- a/latest/modules/index.html +++ b/latest/modules/index.html @@ -99,7 +99,7 @@ @@ -184,6 +184,10 @@

    Modules

    Synapse supports extending its functionality by configuring external modules.

    +

    Note: When using third-party modules, you effectively allow someone else to run +custom code on your Synapse homeserver. Server admins are encouraged to verify the +provenance of the modules they use on their homeserver and make sure the modules aren't +running malicious code on their instance.

    Using modules

    To use a module on Synapse, add it to the modules section of the configuration file:

    modules:
@@ -195,18 +199,30 @@

    Each module is defined by a path to a Python class as well as a configuration. This information for a given module should be available in the module's own documentation.

    -

    Note: When using third-party modules, you effectively allow someone else to run -custom code on your Synapse homeserver. Server admins are encouraged to verify the -provenance of the modules they use on their homeserver and make sure the modules aren't -running malicious code on their instance.

    -

    Also note that we are currently in the process of migrating module interfaces to this -system. While some interfaces might be compatible with it, others still require -configuring modules in another part of Synapse's configuration file.

    +

    Using multiple modules

    +

    The order in which modules are listed in this section is important. When processing an +action that can be handled by several modules, Synapse will always prioritise the module +that appears first (i.e. is the highest in the list). This means:

    + +

    Note that Synapse doesn't allow multiple modules implementing authentication checkers via +the password auth provider feature for the same login type with different fields. If this +happens, Synapse will refuse to start.

    +

    Current status

    +

    We are currently in the process of migrating module interfaces to this system. While some +interfaces might be compatible with it, others still require configuring modules in +another part of Synapse's configuration file.

    Currently, only the following pre-existing interfaces are compatible with this new system:

    diff --git a/latest/modules/password_auth_provider_callbacks.html b/latest/modules/password_auth_provider_callbacks.html new file mode 100644 index 0000000000..115ded8534 --- /dev/null +++ b/latest/modules/password_auth_provider_callbacks.html @@ -0,0 +1,406 @@ + + + + + + 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

    +

    First introduced in Synapse v1.46.0

    +
     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.

    +

    If multiple modules register an auth checker for the same login type but with different +fields, Synapse will refuse to start.

    +

    If multiple modules register an auth checker for the same login type with the same fields, +then the callbacks will be executed in order, until one returns a Matrix User ID (and +optionally a callback). In that case, the return value of that callback will be accepted +and subsequent callbacks will not be fired. If every callback returns None, then the +authentication fails.

    +

    check_3pid_auth

    +

    First introduced in Synapse v1.46.0

    +
    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.

    +

    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 authentication is denied.

    +

    on_logged_out

    +

    First introduced in Synapse v1.46.0

    +
    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.

    +

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

    +

    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/latest/modules/porting_legacy_module.html b/latest/modules/porting_legacy_module.html index b03f0e3aec..e831655ea5 100644 --- a/latest/modules/porting_legacy_module.html +++ b/latest/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).