Document why auth providers aren't validated in the admin API. (#12004)
Since it is reasonable to give a future or past auth provider,
which might not be in the current configuration.
4 files changed, 29 insertions, 2 deletions
diff --git a/changelog.d/12004.doc b/changelog.d/12004.doc
new file mode 100644
index 0000000000..0b4baef210
--- /dev/null
+++ b/changelog.d/12004.doc
@@ -0,0 +1 @@
+Clarify information about external Identity Provider IDs.
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 1bbe237080..4076fcab65 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 8a17b912d3..07020bfb8d 100644
--- a/synapse/module_api/__init__.py
+++ b/synapse/module_api/__init__.py
@@ -653,7 +653,11 @@ class ModuleApi:
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
"""
diff --git a/synapse/storage/databases/main/registration.py b/synapse/storage/databases/main/registration.py
index aac94fa464..17110bb033 100644
--- a/synapse/storage/databases/main/registration.py
+++ b/synapse/storage/databases/main/registration.py
@@ -622,10 +622,13 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
) -> None:
"""Record a mapping from an external user id to a mxid
+ See notes in _record_user_external_id_txn about what constitutes valid 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 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
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 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
"""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 valid 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.
"""
|
