diff --git a/changelogs/client_server/newsfragments/2281.feature b/changelogs/client_server/newsfragments/2281.feature new file mode 100644 index 000000000..7c235423b --- /dev/null +++ b/changelogs/client_server/newsfragments/2281.feature @@ -0,0 +1 @@ +Add ``m.identity_server`` account data for tracking the user's preferred identity server. diff --git a/event-schemas/examples/m.identity_server b/event-schemas/examples/m.identity_server new file mode 100644 index 000000000..32855e9ce --- /dev/null +++ b/event-schemas/examples/m.identity_server @@ -0,0 +1,7 @@ +{ + "$ref": "core/event.json", + "type": "m.identity_server", + "content": { + "base_url": "https://example.org" + } +} diff --git a/event-schemas/schema/m.identity_server b/event-schemas/schema/m.identity_server new file mode 100644 index 000000000..75d2409ff --- /dev/null +++ b/event-schemas/schema/m.identity_server @@ -0,0 +1,23 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml +description: |- + Persists the user's preferred identity server, or preference to not use + an identity server at all, in the user's account data. +properties: + content: + type: object + properties: + base_url: + type: string + description: |- + The URL of the identity server the user prefers to use, or ``null`` + if the user does not want to use an identity server. This value is + similar in structure to the ``base_url`` for identity servers in the + ``.well-known/matrix/client`` schema. + type: + enum: + - m.identity_server + type: string +title: Identity Server Preference +type: object diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 916604a37..1ea98fef1 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1139,6 +1139,41 @@ Current account information {{whoami_cs_http_api}} +Notes on identity servers ++++++++++++++++++++++++++ + +Identity servers in Matrix store bindings (relationships) between a user's third +party identifier, typically email or phone number, and their user ID. Once a user +has chosen an identity server, that identity server should be used by all clients. + +Clients can see which identity server the user has chosen through the ``m.identity_server`` +account data event, as described below. Clients SHOULD refrain from making requests +to any identity server until the presence of ``m.identity_server`` is confirmed as +(not) present. If present, the client SHOULD check for the presence of the ``base_url`` +property in the event's content. If the ``base_url`` is present, the client SHOULD +use the identity server in that property as the identity server for the user. If the +``base_url`` is missing, or the account data event is not present, the client SHOULD +use whichever default value it normally would for an identity server, if applicable. +Clients SHOULD NOT update the account data with the default identity server when the +user is missing an identity server in their account data. + +Clients SHOULD listen for changes to the ``m.identity_server`` account data event +and update the identity server they are contacting as a result. + +If the client offers a way to set the identity server to use, it MUST update the +value of ``m.identity_server`` accordingly. A ``base_url`` of ``null`` MUST be +treated as though the user does not want to use an identity server, disabling all +related functionality as a result. + +Clients SHOULD refrain from populating the account data as a migration step for users +who are lacking the account data, unless the user sets the identity server within +the client to a value. For example, a user which has no ``m.identity_server`` account +data event should not end up with the client's default identity server in their +account data, unless the user first visits their account settings to set the identity +server. + +{{m_identity_server_event}} + Capabilities negotiation ------------------------