OpenCloud
/
MatrixSynapse
mirror of https://github.com/matrix-org/synapse
1
0
Fork 0
Code Issues Releases Wiki Activity

Clean up and clarify "Create or modify Account" Admin API documentation (#15544)

pull/15548/head
Andrew Morgan 2023-05-05 15:51:46 +01:00 committed by GitHub
parent e46d5f3586
commit 7c95b65873
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 72 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -0,0 +1 @@
Clarify documentation of the "Create or modify account" Admin API.

83
docs/admin_api/user_admin_api.md
View File

@ -62,7 +62,7 @@ URL parameters:
- `user_id`: fully-qualified user id: for example, `@user:server.com`.
## Create or modify Account
## Create or modify account
This API allows an administrator to create or modify a user account with a
specific `user_id`.
@ -78,28 +78,29 @@ with a body of:
```json
{
"password": "user_password",
"displayname": "User",
"logout_devices": false,
"displayname": "Alice Marigold",
"avatar_url": "mxc://example.com/abcde12345",
"threepids": [
{
"medium": "email",
"address": "<user_mail_1>"
"address": "alice@example.com"
},
{
"medium": "email",
"address": "<user_mail_2>"
"address": "alice@domain.org"
}
],
"external_ids": [
{
"auth_provider": "<provider1>",
"external_id": "<user_id_provider_1>"
"auth_provider": "example",
"external_id": "12345"
},
{
"auth_provider": "<provider2>",
"external_id": "<user_id_provider_2>"
"auth_provider": "example2",
"external_id": "abc54321"
}
],
"avatar_url": "<avatar_url>",
"admin": false,
"deactivated": false,
"user_type": null
@ -112,41 +113,51 @@ Returns HTTP status code:
URL parameters:
- `user_id`: fully-qualified user id: for example, `@user:server.com`.
- `user_id` - A fully-qualified user id. For example, `@user:server.com`.
Body parameters:
- `password` - string, optional. If provided, the user's password is updated and all
- `password` - **string**, optional. If provided, the user's password is updated and all
devices are logged out, unless `logout_devices` is set to `false`.
- `logout_devices` - bool, optional, defaults to `true`. If set to false, devices aren't
- `logout_devices` - **bool**, optional, defaults to `true`. If set to `false`, devices aren't
logged out even when `password` is provided.
- `displayname` - string, optional, defaults to the value of `user_id`.
- `threepids` - array, optional, allows setting the third-party IDs (email, msisdn)
- `medium` - string. Kind of third-party ID, either `email` or `msisdn`.
- `address` - string. Value of third-party ID.
belonging to a user.
- `external_ids` - array, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). Details in the configuration manual under the
sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
- `auth_provider` - string. ID of the external identity provider. Value of `idp_id`
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
- `displayname` - **string**, optional. If set to an empty string (`""`), the user's display name
will be removed.
- `avatar_url` - **string**, optional. Must be a
[MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).
- `admin` - bool, optional, defaults to `false`.
- `deactivated` - bool, optional. If unspecified, deactivation state will be left
unchanged on existing accounts and set to `false` for new accounts.
A user cannot be erased by deactivating with this API. For details on
deactivating users see [Deactivate Account](#deactivate-account).
- `user_type` - string or null, optional. If provided, the user type will be
adjusted. If `null` given, the user type will be cleared. Other
allowed options are: `bot` and `support`.
If set to an empty string (`""`), the user's avatar is removed.
- `threepids` - **array**, optional. If provided, the user's third-party IDs (email, msisdn) are
entirely replaced with the given list. Each item in the array is an object with the following
fields:
- `medium` - **string**, required. The type of third-party ID, either `email` or `msisdn` (phone number).
- `address` - **string**, required. The third-party ID itself, e.g. `alice@example.com` for `email` or
`447470274584` (for a phone number with country code "44") and `19254857364` (for a phone number
with country code "1") for `msisdn`.
Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove
that threepid from any identity servers it is aware has a binding for it.
- `external_ids` - **array**, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). More details are in the configuration manual under the
sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
- `auth_provider` - **string**, required. The unique, internal ID of the external identity provider.
The same as `idp_id` from the homeserver configuration. Note that no error is raised if the
provided value is not in the homeserver configuration.
- `external_id` - **string**, required. An identifier for the user in the external identity provider.
When the user logs in to the identity provider, this must be the unique ID that they map to.
- `admin` - **bool**, optional, defaults to `false`. Whether the user is a homeserver administrator,
granting them access to the Admin API, among other things.
- `deactivated` - **bool**, optional. If unspecified, deactivation state will be left unchanged.
If the user already exists then optional parameters default to the current value.
Note: the `password` field must also be set if both of the following are true:
- `deactivated` is set to `false` and the user was previously deactivated (you are reactivating this user)
- Users are allowed to set their password on this homeserver (both `password_config.enabled` and
`password_config.localdb_enabled` config options are set to `true`).
Users' passwords are wiped upon account deactivation, hence the need to set a new one here.
In order to re-activate an account `deactivated` must be set to `false`. If
users do not login via single-sign-on, a new `password` must be provided.
Note: a user cannot be erased with this API. For more details on
deactivating and erasing users see [Deactivate Account](#deactivate-account).
- `user_type` - **string** or null, optional. If not provided, the user type will be
not be changed. If `null` is given, the user type will be cleared.
Other allowed options are: `bot` and `support`.
## List Accounts

4
synapse/handlers/profile.py
View File

@ -170,8 +170,8 @@ class ProfileHandler:
displayname_to_set = None
# If the admin changes the display name of a user, the requesting user cannot send
# the join event to update the displayname in the rooms.
# This must be done by the target user himself.
# the join event to update the display name in the rooms.
# This must be done by the target user themselves.
if by_admin:
requester = create_requester(
target_user,

2
synapse/rest/admin/users.py
View File

@ -336,7 +336,7 @@ class UserRestServletV2(RestServlet):
HTTPStatus.CONFLICT, "External id is already in use."
)
if "avatar_url" in body and isinstance(body["avatar_url"], str):
if "avatar_url" in body:
await self.profile_handler.set_avatar_url(
target_user, requester, body["avatar_url"], True
)

16
synapse/storage/databases/main/profile.py
View File

@ -85,6 +85,14 @@ class ProfileWorkerStore(SQLBaseStore):
async def set_profile_displayname(
self, user_id: UserID, new_displayname: Optional[str]
) -> None:
"""
Set the display name of a user.
Args:
user_id: The user's ID.
new_displayname: The new display name. If this is None, the user's display
name is removed.
"""
user_localpart = user_id.localpart
await self.db_pool.simple_upsert(
table="profiles",
@ -99,6 +107,14 @@ class ProfileWorkerStore(SQLBaseStore):
async def set_profile_avatar_url(
self, user_id: UserID, new_avatar_url: Optional[str]
) -> None:
"""
Set the avatar of a user.
Args:
user_id: The user's ID.
new_avatar_url: The new avatar URL. If this is None, the user's avatar is
removed.
"""
user_localpart = user_id.localpart
await self.db_pool.simple_upsert(
table="profiles",

6
synapse/util/msisdn.py
View File

@ -22,12 +22,16 @@ def phone_number_to_msisdn(country: str, number: str) -> str:
Takes an ISO-3166-1 2 letter country code and phone number and
returns an msisdn representing the canonical version of that
phone number.
As an example, if `country` is "GB" and `number` is "7470674927", this
function will return "447470674927".
Args:
country: ISO-3166-1 2 letter country code
number: Phone number in a national or international format
Returns:
The canonical form of the phone number, as an msisdn
The canonical form of the phone number, as an msisdn.
Raises:
SynapseError if the number could not be parsed.
"""