From 7079930af570f727e74d5890488de6ae54a80d43 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 13 May 2021 13:16:02 -0400 Subject: [PATCH 1/3] Update SSO mapping providers documentation about identifiers and localparts. --- docs/sso_mapping_providers.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index 50020d1a4ad1..985043956c4c 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -67,8 +67,8 @@ A custom mapping provider must specify the following methods: - Arguments: - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user information from. - - This method must return a string, which is the unique identifier for the - user. Commonly the ``sub`` claim of the response. + - This method must return a string, which is the unique, immutable identifier + for the user. Commonly the ``sub`` claim of the response. * `map_user_attributes(self, userinfo, token, failures)` - This method must be async. - Arguments: @@ -87,7 +87,9 @@ A custom mapping provider must specify the following methods: `localpart` value, such as `john.doe1`. - Returns a dictionary with two keys: - `localpart`: A string, used to generate the Matrix ID. If this is - `None`, the user is prompted to pick their own username. + `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. * `get_extra_attributes(self, userinfo, token)` - This method must be async. @@ -153,8 +155,8 @@ A custom mapping provider must specify the following methods: information from. - `client_redirect_url` - A string, the URL that the client will be redirected to. - - This method must return a string, which is the unique identifier for the - user. Commonly the ``uid`` claim of the response. + - This method must return a string, which is the unique, immutable identifier + for the user. Commonly the ``uid`` claim of the response. * `saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)` - Arguments: - `saml_response` - A `saml2.response.AuthnResponse` object to extract user @@ -172,8 +174,10 @@ A custom mapping provider must specify the following methods: redirected to. - This method must return a dictionary, which will then be used by Synapse to build a new user. The following keys are allowed: - * `mxid_localpart` - The mxid localpart of the new user. If this is - `None`, the user is prompted to pick their own username. + * `mxid_localpart` - A string, the mxid localpart of the new user. If this is + `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` - The displayname of the new user. If not provided, will default to the value of `mxid_localpart`. * `emails` - A list of emails for the new user. If not provided, will From 2a009cbfb5f7d28f696aec34b83615c99ea44903 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 13 May 2021 13:17:32 -0400 Subject: [PATCH 2/3] Newsfragment --- changelog.d/9980.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/9980.doc diff --git a/changelog.d/9980.doc b/changelog.d/9980.doc new file mode 100644 index 000000000000..d30ed0601da6 --- /dev/null +++ b/changelog.d/9980.doc @@ -0,0 +1 @@ +Clarify documentation around SSO mapping providers generating unique IDs and localparts. From ded55ccebbb55edf5155abd046e79c1725c715a0 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 13 May 2021 13:59:41 -0400 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- 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 985043956c4c..6db2dc8be5b9 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -68,7 +68,7 @@ A custom mapping provider must specify the following methods: - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user information from. - This method must return a string, which is the unique, immutable identifier - for the user. Commonly the ``sub`` claim of the response. + for the user. Commonly the `sub` claim of the response. * `map_user_attributes(self, userinfo, token, failures)` - This method must be async. - Arguments: @@ -156,7 +156,7 @@ A custom mapping provider must specify the following methods: - `client_redirect_url` - A string, the URL that the client will be redirected to. - This method must return a string, which is the unique, immutable identifier - for the user. Commonly the ``uid`` claim of the response. + for the user. Commonly the `uid` claim of the response. * `saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)` - Arguments: - `saml_response` - A `saml2.response.AuthnResponse` object to extract user @@ -176,8 +176,8 @@ A custom mapping provider must specify the following methods: to build a new user. The following keys are allowed: * `mxid_localpart` - A string, the mxid localpart of the new user. If this is `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. + 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` - The displayname of the new user. If not provided, will default to the value of `mxid_localpart`. * `emails` - A list of emails for the new user. If not provided, will