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.
This commit is contained in:
Patrick Cloke 2022-02-18 12:24:25 -05:00 committed by GitHub
parent 284ea2025a
commit 444b04058b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 29 additions and 2 deletions

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

@ -0,0 +1 @@
Clarify information about external Identity Provider IDs.

View File

@ -126,7 +126,8 @@ Body parameters:
[Sample Configuration File](../usage/configuration/homeserver_sample_config.html) [Sample Configuration File](../usage/configuration/homeserver_sample_config.html)
section `sso` and `oidc_providers`. section `sso` and `oidc_providers`.
- `auth_provider` - string. ID of the external identity provider. Value of `idp_id` - `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. - `external_id` - string, user ID in the external identity provider.
- `avatar_url` - string, optional, must be a - `avatar_url` - string, optional, must be a
[MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris). [MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).

View File

@ -653,7 +653,11 @@ class ModuleApi:
Added in Synapse v1.9.0. Added in Synapse v1.9.0.
Args: 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 external_id: id on that system
user_id: complete mxid that it is mapped to user_id: complete mxid that it is mapped to
""" """

View File

@ -622,10 +622,13 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
) -> None: ) -> None:
"""Record a mapping from an external user id to a mxid """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: Args:
auth_provider: identifier for the remote auth provider auth_provider: identifier for the remote auth provider
external_id: id on that system external_id: id on that system
user_id: complete mxid that it is mapped to user_id: complete mxid that it is mapped to
Raises: Raises:
ExternalIDReuseException if the new external_id could not be mapped. ExternalIDReuseException if the new external_id could not be mapped.
""" """
@ -648,6 +651,21 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
external_id: str, external_id: str,
user_id: str, user_id: str,
) -> None: ) -> 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( self.db_pool.simple_insert_txn(
txn, txn,
@ -687,10 +705,13 @@ class RegistrationWorkerStore(CacheInvalidationWorkerStore):
"""Replace mappings from external user ids to a mxid in a single transaction. """Replace mappings from external user ids to a mxid in a single transaction.
All mappings are deleted and the new ones are created. All mappings are deleted and the new ones are created.
See notes in _record_user_external_id_txn about what constitutes valid data.
Args: Args:
record_external_ids: record_external_ids:
List with tuple of auth_provider and external_id to record List with tuple of auth_provider and external_id to record
user_id: complete mxid that it is mapped to user_id: complete mxid that it is mapped to
Raises: Raises:
ExternalIDReuseException if the new external_id could not be mapped. ExternalIDReuseException if the new external_id could not be mapped.
""" """