summary refs log tree commit diff
path: root/docs/modules
diff options
context:
space:
mode:
authorErik Johnston <erik@matrix.org>2023-06-26 15:12:20 +0100
committerGitHub <noreply@github.com>2023-06-26 14:12:20 +0000
commit25c55a9d2267b09da3e18090ee538782d6771a27 (patch)
tree7d8aced4b661f7a2d260dba9a5f6f76693ee48fe /docs/modules
parentBump types-opentracing from 2.4.10.4 to 2.4.10.5 (#15830) (diff)
downloadsynapse-25c55a9d2267b09da3e18090ee538782d6771a27.tar.xz
Add login spam checker API (#15838)
Diffstat (limited to 'docs/modules')
-rw-r--r--docs/modules/spam_checker_callbacks.md36
1 files changed, 36 insertions, 0 deletions
diff --git a/docs/modules/spam_checker_callbacks.md b/docs/modules/spam_checker_callbacks.md
index 1a0c6ec954..ffdfe6082e 100644
--- a/docs/modules/spam_checker_callbacks.md
+++ b/docs/modules/spam_checker_callbacks.md
@@ -348,6 +348,42 @@ callback returns `False`, Synapse falls through to the next one. The value of th
 callback that does not return `False` will be used. If this happens, Synapse will not call
 any of the subsequent implementations of this callback.
 
+
+### `check_login_for_spam`
+
+_First introduced in Synapse v1.87.0_
+
+```python
+async def check_login_for_spam(
+    user_id: str,
+    device_id: Optional[str],
+    initial_display_name: Optional[str],
+    request_info: Collection[Tuple[Optional[str], str]],
+    auth_provider_id: Optional[str] = None,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]
+```
+
+Called when a user logs in.
+
+The arguments passed to this callback are:
+
+* `user_id`: The user ID the user is logging in with
+* `device_id`: The device ID the user is re-logging into.
+* `initial_display_name`: The device display name, if any.
+* `request_info`: A collection of tuples, which first item is a user agent, and which
+  second item is an IP address. These user agents and IP addresses are the ones that were
+  used during the login process.
+* `auth_provider_id`: The identifier of the SSO authentication provider, if any.
+
+If multiple modules implement this callback, they will be considered in order. If a
+callback returns `synapse.module_api.NOT_SPAM`, Synapse falls through to the next one.
+The value of the first callback that does not return `synapse.module_api.NOT_SPAM` will
+be used. If this happens, Synapse will not call any of the subsequent implementations of
+this callback.
+
+*Note:* This will not be called when a user registers.
+
+
 ## Example
 
 The example below is a module that implements the spam checker callback