diff --git a/changelog.d/9980.doc b/changelog.d/9980.doc
new file mode 100644
index 0000000000..d30ed0601d
--- /dev/null
+++ b/changelog.d/9980.doc
@@ -0,0 +1 @@
+Clarify documentation around SSO mapping providers generating unique IDs and localparts.
diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md
index 50020d1a4a..6db2dc8be5 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
|
