From 6dd7fa12dc18835b18c0632b89c2563d806cd8ef Mon Sep 17 00:00:00 2001 From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> Date: Thu, 4 Aug 2022 14:06:02 +0200 Subject: Update some outdated information on `sso_mapping_providers.md` (#13449) --- docs/sso_mapping_providers.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/sso_mapping_providers.md') diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index 7b4ddc5b74..817499149f 100644 --- a/docs/sso_mapping_providers.md +++ b/docs/sso_mapping_providers.md @@ -22,7 +22,7 @@ choose their own username. In the first case - where users are automatically allocated a Matrix ID - it is the responsibility of the mapping provider to normalise the SSO attributes and map them to a valid Matrix ID. The [specification for Matrix -IDs](https://matrix.org/docs/spec/appendices#user-identifiers) has some +IDs](https://spec.matrix.org/latest/appendices/#user-identifiers) has some information about what is considered valid. If the mapping provider does not assign a Matrix ID, then Synapse will @@ -37,9 +37,10 @@ as Synapse). The Synapse config is then modified to point to the mapping provide ## OpenID Mapping Providers The OpenID mapping provider can be customized by editing the -`oidc_config.user_mapping_provider.module` config option. +[`oidc_providers.user_mapping_provider.module`](usage/configuration/config_documentation.md#oidc_providers) +config option. -`oidc_config.user_mapping_provider.config` allows you to provide custom +`oidc_providers.user_mapping_provider.config` allows you to provide custom configuration options to the module. Check with the module's documentation for what options it provides (if any). The options listed by default are for the user mapping provider built in to Synapse. If using a custom module, you should @@ -58,7 +59,7 @@ A custom mapping provider must specify the following methods: - This method should have the `@staticmethod` decoration. - Arguments: - `config` - A `dict` representing the parsed content of the - `oidc_config.user_mapping_provider.config` homeserver config option. + `oidc_providers.user_mapping_provider.config` homeserver config option. Runs on homeserver startup. Providers should extract and validate any option values they need here. - Whatever is returned will be passed back to the user mapping provider module's @@ -102,7 +103,7 @@ A custom mapping provider must specify the following methods: will be returned as part of the response during a successful login. Note that care should be taken to not overwrite any of the parameters - usually returned as part of the [login response](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-login). + usually returned as part of the [login response](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login). ### Default OpenID Mapping Provider @@ -113,7 +114,8 @@ specified in the config. It is located at ## SAML Mapping Providers The SAML mapping provider can be customized by editing the -`saml2_config.user_mapping_provider.module` config option. +[`saml2_config.user_mapping_provider.module`](docs/usage/configuration/config_documentation.md#saml2_config) +config option. `saml2_config.user_mapping_provider.config` allows you to provide custom configuration options to the module. Check with the module's documentation for -- cgit 1.5.1 From 16e1a9d9a7884967da390ef967b942a5e35e8f6c Mon Sep 17 00:00:00 2001 From: Peter Scheu <32014443+peterscheu-aceart@users.noreply.github.com> Date: Wed, 21 Sep 2022 15:08:16 +0200 Subject: Correct documentation for map_user_attributes of OpenID Mapping Providers (#13836) Co-authored-by: David Robertson --- changelog.d/13836.doc | 1 + docs/sso_mapping_providers.md | 12 +++++++++--- synapse/handlers/sso.py | 3 +++ 3 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 changelog.d/13836.doc (limited to 'docs/sso_mapping_providers.md') diff --git a/changelog.d/13836.doc b/changelog.d/13836.doc new file mode 100644 index 0000000000..f2edab00f4 --- /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`. diff --git a/docs/sso_mapping_providers.md b/docs/sso_mapping_providers.md index 817499149f..9f5e5fbbe1 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. - - `displayname`: An optional string, the display name for the user. + - `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. * `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 1e171f3f71..6bc1cbd787 100644 --- a/synapse/handlers/sso.py +++ b/synapse/handlers/sso.py @@ -128,6 +128,9 @@ class SsoIdentityProvider(Protocol): @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. -- cgit 1.5.1