Update SSO mapping providers documentation about unique IDs. (#9980)

This commit is contained in:
Patrick Cloke 2021-05-13 14:37:20 -04:00 committed by GitHub
parent 451f25172a
commit d19bccdbec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 12 additions and 7 deletions

1
changelog.d/9980.doc Normal file
View File

@ -0,0 +1 @@
Clarify documentation around SSO mapping providers generating unique IDs and localparts.

View File

@ -67,8 +67,8 @@ A custom mapping provider must specify the following methods:
- Arguments: - Arguments:
- `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user - `userinfo` - A `authlib.oidc.core.claims.UserInfo` object to extract user
information from. information from.
- This method must return a string, which is the unique identifier for the - This method must return a string, which is the unique, immutable identifier
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)` * `map_user_attributes(self, userinfo, token, failures)`
- This method must be async. - This method must be async.
- Arguments: - Arguments:
@ -87,7 +87,9 @@ A custom mapping provider must specify the following methods:
`localpart` value, such as `john.doe1`. `localpart` value, such as `john.doe1`.
- Returns a dictionary with two keys: - Returns a dictionary with two keys:
- `localpart`: A string, used to generate the Matrix ID. If this is - `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. - `displayname`: An optional string, the display name for the user.
* `get_extra_attributes(self, userinfo, token)` * `get_extra_attributes(self, userinfo, token)`
- This method must be async. - This method must be async.
@ -153,8 +155,8 @@ A custom mapping provider must specify the following methods:
information from. information from.
- `client_redirect_url` - A string, the URL that the client will be - `client_redirect_url` - A string, the URL that the client will be
redirected to. redirected to.
- This method must return a string, which is the unique identifier for the - This method must return a string, which is the unique, immutable identifier
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)` * `saml_response_to_user_attributes(self, saml_response, failures, client_redirect_url)`
- Arguments: - Arguments:
- `saml_response` - A `saml2.response.AuthnResponse` object to extract user - `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. redirected to.
- This method must return a dictionary, which will then be used by Synapse - This method must return a dictionary, which will then be used by Synapse
to build a new user. The following keys are allowed: to build a new user. The following keys are allowed:
* `mxid_localpart` - The mxid localpart of the new user. If this is * `mxid_localpart` - A string, the mxid localpart of the new user. 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` - The displayname of the new user. If not provided, will default to * `displayname` - The displayname of the new user. If not provided, will default to
the value of `mxid_localpart`. the value of `mxid_localpart`.
* `emails` - A list of emails for the new user. If not provided, will * `emails` - A list of emails for the new user. If not provided, will