diff --git a/changelog.d/13842.removal b/changelog.d/13842.removal
new file mode 100644
index 0000000000..cbcff38e91
--- /dev/null
+++ b/changelog.d/13842.removal
@@ -0,0 +1 @@
+Deprecate the `generate_short_term_login_token` method in favor of an async `create_login_token` method in the Module API.
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 002ef70059..b81385b191 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -128,6 +128,39 @@ you may specify `enable_legacy_metrics: false` in your homeserver configuration.
A list of affected metrics is available on the [Metrics How-to page](https://matrix-org.github.io/synapse/v1.69/metrics-howto.html?highlight=metrics%20deprecated#renaming-of-metrics--deprecation-of-old-names-in-12).
+## Deprecation of the `generate_short_term_login_token` module API method
+
+The following method of the module API has been deprecated, and is scheduled to
+be remove in v1.71.0:
+
+```python
+def generate_short_term_login_token(
+ self,
+ user_id: str,
+ duration_in_ms: int = (2 * 60 * 1000),
+ auth_provider_id: str = "",
+ auth_provider_session_id: Optional[str] = None,
+) -> str:
+ ...
+```
+
+It has been replaced by an asynchronous equivalent:
+
+```python
+async def create_login_token(
+ self,
+ user_id: str,
+ duration_in_ms: int = (2 * 60 * 1000),
+ auth_provider_id: Optional[str] = None,
+ auth_provider_session_id: Optional[str] = None,
+) -> str:
+ ...
+```
+
+Synapse will log a warning when a module uses the deprecated method, to help
+administrators find modules using it.
+
+
# Upgrading to v1.68.0
Two changes announced in the upgrade notes for v1.67.0 have now landed in v1.68.0.
diff --git a/synapse/module_api/__init__.py b/synapse/module_api/__init__.py
index b7b2d3b8c5..6a6ae208d1 100644
--- a/synapse/module_api/__init__.py
+++ b/synapse/module_api/__init__.py
@@ -748,6 +748,40 @@ class ModuleApi:
)
)
+ async def create_login_token(
+ self,
+ user_id: str,
+ duration_in_ms: int = (2 * 60 * 1000),
+ auth_provider_id: Optional[str] = None,
+ auth_provider_session_id: Optional[str] = None,
+ ) -> str:
+ """Create a login token suitable for m.login.token authentication
+
+ Added in Synapse v1.69.0.
+
+ Args:
+ user_id: gives the ID of the user that the token is for
+
+ duration_in_ms: the time that the token will be valid for
+
+ auth_provider_id: the ID of the SSO IdP that the user used to authenticate
+ to get this token, if any. This is encoded in the token so that
+ /login can report stats on number of successful logins by IdP.
+
+ auth_provider_session_id: The session ID got during login from the SSO IdP,
+ if any.
+ """
+ # The deprecated `generate_short_term_login_token` method defaulted to an empty
+ # string for the `auth_provider_id` because of how the underlying macaroon was
+ # generated. This will change to a proper NULL-able field when the tokens get
+ # moved to the database.
+ return self._hs.get_macaroon_generator().generate_short_term_login_token(
+ user_id,
+ auth_provider_id or "",
+ auth_provider_session_id,
+ duration_in_ms,
+ )
+
def generate_short_term_login_token(
self,
user_id: str,
@@ -759,6 +793,9 @@ class ModuleApi:
Added in Synapse v1.9.0.
+ This was deprecated in Synapse v1.69.0 in favor of create_login_token, and will
+ be removed in Synapse 1.71.0.
+
Args:
user_id: gives the ID of the user that the token is for
@@ -768,6 +805,11 @@ class ModuleApi:
to get this token, if any. This is encoded in the token so that
/login can report stats on number of successful logins by IdP.
"""
+ logger.warn(
+ "A module configured on this server uses ModuleApi.generate_short_term_login_token(), "
+ "which is deprecated in favor of ModuleApi.create_login_token(), and will be removed in "
+ "Synapse 1.71.0",
+ )
return self._hs.get_macaroon_generator().generate_short_term_login_token(
user_id,
auth_provider_id,
|
