From 35348aeb14918b5c3e0ddbf0b9f305fd2ce8b760 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 16 Feb 2022 07:34:48 -0500 Subject: [PATCH 1/5] Add some comments. --- .../storage/databases/main/registration.py | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/synapse/storage/databases/main/registration.py b/synapse/storage/databases/main/registration.py index aac94fa46444..e0e20a399a93 100644 --- a/synapse/storage/databases/main/registration.py +++ b/synapse/storage/databases/main/registration.py @@ -622,10 +622,13 @@ async def record_user_external_id( ) -> None: """Record a mapping from an external user id to a mxid + See notes in _record_user_external_id_txn about what constitutes validate data. + Args: auth_provider: identifier for the remote auth provider external_id: id on that system user_id: complete mxid that it is mapped to + Raises: ExternalIDReuseException if the new external_id could not be mapped. """ @@ -648,6 +651,21 @@ def _record_user_external_id_txn( external_id: str, user_id: str, ) -> None: + """ + Record a mapping from an external user id to a mxid. + + Note that the auth provider IDs (and the external IDs) are not validated + against configured IdPs as Synapse does not know its relationship to + external systems. For example, it might be useful to pre-configure users + before enabling a new IdP or an IdP might be temporarily offline, but + still valid. + + Args: + txn: The database transaction. + auth_provider: identifier for the remote auth provider + external_id: id on that system + user_id: complete mxid that it is mapped to + """ self.db_pool.simple_insert_txn( txn, @@ -687,10 +705,13 @@ async def replace_user_external_id( """Replace mappings from external user ids to a mxid in a single transaction. All mappings are deleted and the new ones are created. + See notes in _record_user_external_id_txn about what constitutes validate data. + Args: record_external_ids: List with tuple of auth_provider and external_id to record user_id: complete mxid that it is mapped to + Raises: ExternalIDReuseException if the new external_id could not be mapped. """ From af9b7dc8d76dc0f278f37fa29adc9371bac11d66 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 16 Feb 2022 07:36:30 -0500 Subject: [PATCH 2/5] Newsfragment --- changelog.d/12004.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/12004.doc diff --git a/changelog.d/12004.doc b/changelog.d/12004.doc new file mode 100644 index 000000000000..4a72fb435905 --- /dev/null +++ b/changelog.d/12004.doc @@ -0,0 +1 @@ +Clarify information about external IdP IDs. From dd6c60f056c3a8bf4ea44795c896bbc49332829a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 17 Feb 2022 07:30:57 -0500 Subject: [PATCH 3/5] Clarify changelog. Co-authored-by: reivilibre --- changelog.d/12004.doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/12004.doc b/changelog.d/12004.doc index 4a72fb435905..0b4baef21035 100644 --- a/changelog.d/12004.doc +++ b/changelog.d/12004.doc @@ -1 +1 @@ -Clarify information about external IdP IDs. +Clarify information about external Identity Provider IDs. From 797dbaa33209b364f258acac34a4a0cb29baa9bc Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 17 Feb 2022 07:31:41 -0500 Subject: [PATCH 4/5] Fix typo. --- synapse/storage/databases/main/registration.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/synapse/storage/databases/main/registration.py b/synapse/storage/databases/main/registration.py index e0e20a399a93..17110bb03314 100644 --- a/synapse/storage/databases/main/registration.py +++ b/synapse/storage/databases/main/registration.py @@ -622,7 +622,7 @@ async def record_user_external_id( ) -> None: """Record a mapping from an external user id to a mxid - See notes in _record_user_external_id_txn about what constitutes validate data. + See notes in _record_user_external_id_txn about what constitutes valid data. Args: auth_provider: identifier for the remote auth provider @@ -705,7 +705,7 @@ async def replace_user_external_id( """Replace mappings from external user ids to a mxid in a single transaction. All mappings are deleted and the new ones are created. - See notes in _record_user_external_id_txn about what constitutes validate data. + See notes in _record_user_external_id_txn about what constitutes valid data. Args: record_external_ids: From cdd5f4b5743753769ab6747dac8188cb7115cf46 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 18 Feb 2022 11:57:08 -0500 Subject: [PATCH 5/5] Update more documentation. --- docs/admin_api/user_admin_api.md | 3 ++- synapse/module_api/__init__.py | 6 +++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md index 1bbe23708055..4076fcab65f1 100644 --- a/docs/admin_api/user_admin_api.md +++ b/docs/admin_api/user_admin_api.md @@ -126,7 +126,8 @@ Body parameters: [Sample Configuration File](../usage/configuration/homeserver_sample_config.html) section `sso` and `oidc_providers`. - `auth_provider` - string. ID of the external identity provider. Value of `idp_id` - in homeserver configuration. + in the homeserver configuration. Note that no error is raised if the provided + value is not in the homeserver configuration. - `external_id` - string, user ID in the external identity provider. - `avatar_url` - string, optional, must be a [MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris). diff --git a/synapse/module_api/__init__.py b/synapse/module_api/__init__.py index d4fca369231a..88f6182b56c8 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -648,7 +648,11 @@ def record_user_external_id( Added in Synapse v1.9.0. Args: - auth_provider: identifier for the remote auth provider + auth_provider: identifier for the remote auth provider, see `sso` and + `oidc_providers` in the homeserver configuration. + + Note that no error is raised if the provided value is not in the + homeserver configuration. external_id: id on that system user_id: complete mxid that it is mapped to """