Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Deprecate the generate_short_term_login_token method in favor of an async create_login_token method in the Module API. #13842

Merged
merged 5 commits into from
Oct 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/13842.removal
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Deprecate the `generate_short_term_login_token` method in favor of an async `create_login_token` method in the Module API.
33 changes: 33 additions & 0 deletions docs/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
42 changes: 42 additions & 0 deletions synapse/module_api/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -748,6 +748,40 @@ 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.
babolivier marked this conversation as resolved.
Show resolved Hide resolved

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 "",
babolivier marked this conversation as resolved.
Show resolved Hide resolved
auth_provider_session_id,
duration_in_ms,
)

def generate_short_term_login_token(
self,
user_id: str,
Expand All @@ -759,6 +793,9 @@ def generate_short_term_login_token(

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

Expand All @@ -768,6 +805,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.
"""
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,
Expand Down