From 1811f9ab3cadbbca5de6ca749c9b84d6f8983991 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Mon, 19 Sep 2022 17:45:17 +0200 Subject: [PATCH 1/4] Deprecate the `generate_short_term_login_token` method in favor of an async `create_login_token` method in the Module API. Signed-off-by: Quentin Gliech --- changelog.d/13842.removal | 1 + synapse/module_api/__init__.py | 38 ++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 changelog.d/13842.removal diff --git a/changelog.d/13842.removal b/changelog.d/13842.removal new file mode 100644 index 000000000000..cbcff38e91ab --- /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/synapse/module_api/__init__.py b/synapse/module_api/__init__.py index 87ba154cb737..45d60f7c04aa 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -14,6 +14,7 @@ # limitations under the License. import email.utils import logging +import warnings from typing import ( TYPE_CHECKING, Any, @@ -748,6 +749,36 @@ def record_user_external_id( ) ) + 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. + """ + 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 +790,8 @@ def generate_short_term_login_token( Added in Synapse v1.9.0. + This is deprecated in favor of create_login_token. + Args: user_id: gives the ID of the user that the token is for @@ -768,6 +801,11 @@ def generate_short_term_login_token( 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. """ + warnings.warn( + "ModuleApi.generate_short_term_login_token() is deprecated " + "in favor of ModuleApi.create_login_token().", + DeprecationWarning, + ) return self._hs.get_macaroon_generator().generate_short_term_login_token( user_id, auth_provider_id, From e85df99de0729964c80ba31be59a8519c607773b Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Tue, 4 Oct 2022 11:55:11 +0200 Subject: [PATCH 2/4] Apply suggestions from code review --- synapse/module_api/__init__.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/synapse/module_api/__init__.py b/synapse/module_api/__init__.py index 45d60f7c04aa..dd1403619beb 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -14,7 +14,6 @@ # limitations under the License. import email.utils import logging -import warnings from typing import ( TYPE_CHECKING, Any, @@ -790,7 +789,8 @@ def generate_short_term_login_token( Added in Synapse v1.9.0. - This is deprecated in favor of create_login_token. + 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 @@ -801,10 +801,10 @@ def generate_short_term_login_token( 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. """ - warnings.warn( - "ModuleApi.generate_short_term_login_token() is deprecated " - "in favor of ModuleApi.create_login_token().", - DeprecationWarning, + 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, From 3d643c4bf09bb857b50f8a7ad811ba17832d9ceb Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 5 Oct 2022 11:37:02 +0200 Subject: [PATCH 3/4] Upgrade notes --- docs/upgrade.md | 33 +++++++++++++++++++++++++++++++++ synapse/module_api/__init__.py | 4 ++++ 2 files changed, 37 insertions(+) diff --git a/docs/upgrade.md b/docs/upgrade.md index 002ef7005985..c21f21f87e30 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 a 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 4778722c5e07..6a6ae208d157 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -771,6 +771,10 @@ async def create_login_token( 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 "", From 04f223ce5d222aa536405f06da61cb9c90cb8c9c Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 6 Oct 2022 11:20:48 +0200 Subject: [PATCH 4/4] Update docs/upgrade.md --- docs/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade.md b/docs/upgrade.md index c21f21f87e30..b81385b19183 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -128,7 +128,7 @@ 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 a module API method +## 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: