From a71feb3c86a19e206cd8846d353c0178c4dfe799 Mon Sep 17 00:00:00 2001 From: Peter Scheu <32014443+peterscheu-aceart@users.noreply.github.com> Date: Mon, 19 Sep 2022 11:58:42 +0200 Subject: [PATCH 1/4] Update sso_mapping_providers.md see [/synapse/handlers/sso.py L130](https://github.com/matrix-org/synapse/blob/fe1daad67237c2154a3d8d8cdf6c603f0d33682e/synapse/handlers/sso.py#L130) --- docs/sso_mapping_providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index 817499149f90..f2e6dd2cda05 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -91,7 +91,7 @@ A custom mapping provider must specify the following methods: `None`, the user is prompted to pick their own username. This is only used during a user's first login. Once a localpart has been associated with a remote user ID (see `get_remote_user_id`) it cannot be updated. - - `displayname`: An optional string, the display name for the user. + - `display_name`: An optional string, the display name for the user. * `async def get_extra_attributes(self, userinfo, token)` - This method must be async. - Arguments: From e7d337c3b1f78c8d1fdcec891dd19773bb5d4048 Mon Sep 17 00:00:00 2001 From: Peter Scheu Date: Mon, 19 Sep 2022 12:26:47 +0200 Subject: [PATCH 2/4] add changelog --- changelog.d/13836.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/13836.doc diff --git a/changelog.d/13836.doc b/changelog.d/13836.doc new file mode 100644 index 000000000000..f2edab00f4ed --- /dev/null +++ b/changelog.d/13836.doc @@ -0,0 +1 @@ +Fix a mistake in sso_mapping_providers.md: `map_user_attributes` is expected to return `display_name` not `displayname`. From 87e48b080ed1df3186ae079c4521453caa0c4ec9 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Wed, 21 Sep 2022 12:19:40 +0100 Subject: [PATCH 3/4] Also describe new attributes while I'm here (/me wishes we could use Sphinx autodoc here) --- docs/sso_mapping_providers.md | 10 ++++++++-- synapse/handlers/sso.py | 3 +++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index f2e6dd2cda05..bf0435c86f00 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -73,8 +73,8 @@ A custom mapping provider must specify the following methods: * `async def map_user_attributes(self, userinfo, token, failures)` - This method must be async. - Arguments: - - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user - information from. + - `userinfo` - An [`authlib.oidc.core.claims.UserInfo`](https://docs.authlib.org/en/latest/specs/oidc.html#authlib.oidc.core.UserInfo) + object to extract user information from. - `token` - A dictionary which includes information necessary to make further requests to the OpenID provider. - `failures` - An `int` that represents the amount of times the returned @@ -91,7 +91,13 @@ A custom mapping provider must specify the following methods: `None`, the user is prompted to pick their own username. This is only used during a user's first login. Once a localpart has been associated with a remote user ID (see `get_remote_user_id`) it cannot be updated. + - `confirm_localpart`: A boolean. If a `localpart` string is returned from + this method and `confirm_localpart` is `True`, Synapse will ask users to + confirm their Matrix ID. Otherwise Synapse will not ask for + confirmation. If omitted, defaults to `False`. - `display_name`: An optional string, the display name for the user. + - `emails`: A list of strings, the email address(es) to associate with + this user. If omitted, defaults to an empty list. * `async def get_extra_attributes(self, userinfo, token)` - This method must be async. - Arguments: diff --git a/synapse/handlers/sso.py b/synapse/handlers/sso.py index 1e171f3f7115..6bc1cbd78790 100644 --- a/synapse/handlers/sso.py +++ b/synapse/handlers/sso.py @@ -128,6 +128,9 @@ async def handle_redirect_request( @attr.s(auto_attribs=True) class UserAttributes: + # NB: This struct is documented in docs/sso_mapping_providers.md so that users can + # populate it with data from their own mapping providers. + # the localpart of the mxid that the mapper has assigned to the user. # if `None`, the mapper has not picked a userid, and the user should be prompted to # enter one. From 48fa7ef0e07193e41844a3b9163fda0b2d537f94 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Wed, 21 Sep 2022 13:25:23 +0100 Subject: [PATCH 4/4] Reword confirm_localpart --- docs/sso_mapping_providers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index bf0435c86f00..9f5e5fbbe152 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -91,10 +91,10 @@ A custom mapping provider must specify the following methods: `None`, the user is prompted to pick their own username. This is only used during a user's first login. Once a localpart has been associated with a remote user ID (see `get_remote_user_id`) it cannot be updated. - - `confirm_localpart`: A boolean. If a `localpart` string is returned from - this method and `confirm_localpart` is `True`, Synapse will ask users to - confirm their Matrix ID. Otherwise Synapse will not ask for - confirmation. If omitted, defaults to `False`. + - `confirm_localpart`: A boolean. If set to `True`, when a `localpart` + string is returned from this method, Synapse will prompt the user to + either accept this localpart or pick their own username. Otherwise this + option has no effect. If omitted, defaults to `False`. - `display_name`: An optional string, the display name for the user. - `emails`: A list of strings, the email address(es) to associate with this user. If omitted, defaults to an empty list.