From 2b0119e0b0934fe709b92992a22021d620e37688 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 14 May 2025 12:59:10 +0200 Subject: [PATCH 1/7] Split account registration and management section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since account locking and suspension are authentication API agnostic, this is a pre-requisite to adding the new OAuth 2.0-based API. This also splits the endpoints that where all included in the registration OpenAPI data, to separate them cleanly in the spec, and avoid having deactivation show before registration. Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 14 +- .../client-server/account_deactivation.yaml | 141 ++++++++ .../client-server/password_management.yaml | 242 ++++++++++++++ data/api/client-server/registration.yaml | 309 ------------------ 4 files changed, 395 insertions(+), 311 deletions(-) create mode 100644 data/api/client-server/account_deactivation.yaml create mode 100644 data/api/client-server/password_management.yaml diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0b2a8346..4933eb20 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1456,11 +1456,13 @@ forwarded to the login endpoint during the login process. For example: GET /_matrix/static/client/login/?device_id=GHTYAJCE -### Account registration and management +### Account registration {{% http-api spec="client-server" api="registration" %}} -#### Notes on password management +### Account management + +#### Password management {{% boxes/warning %}} Clients SHOULD enforce that the password provided is suitably complex. @@ -1469,6 +1471,14 @@ number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% /boxes/warning %}} +{{% http-api spec="client-server" api="password_management" %}} + +#### Account deactivation + +{{% http-api spec="client-server" api="account_deactivation" %}} + +### Account moderation + #### Account locking {{% added-in v="1.12" %}} diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml new file mode 100644 index 00000000..467af659 --- /dev/null +++ b/data/api/client-server/account_deactivation.yaml @@ -0,0 +1,141 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2022 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server Account Deactivation API + version: 1.0.0 +paths: + /account/deactivate: + post: + summary: Deactivate a user's account. + description: |- + Deactivate the user's account, removing all ability for the user to + login again. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An access token should be submitted to this endpoint if the client has + an active session. + + The homeserver may change the flows available depending on whether a + valid access token is provided. + + Unlike other endpoints, this endpoint does not take an `id_access_token` + parameter because the homeserver is expected to sign the request to the + identity server instead. + security: + - {} + - accessTokenQuery: [] + - accessTokenBearer: [] + operationId: deactivateAccount + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + id_server: + type: string + description: |- + The identity server to unbind all of the user's 3PIDs from. + If not provided, the homeserver MUST use the `id_server` + that was originally use to bind each identifier. If the + homeserver does not know which `id_server` that was, + it must return an `id_server_unbind_result` of + `no-support`. + example: example.org + erase: + x-addedInMatrixVersion: "1.10" + type: boolean + description: |- + Whether the user would like their content to be erased as + much as possible from the server. + + Erasure means that any users (or servers) which join the + room after the erasure request are served redacted copies of + the events sent by this account. Users which had visibility + on those events prior to the erasure are still able to see + unredacted copies. No redactions are sent and the erasure + request is not shared over federation, so other servers + might still serve unredacted copies. + + The server should additionally erase any non-event data + associated with the user, such as [account data](/client-server-api/#client-config) + and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information). + + Defaults to `false` if not present. + required: true + responses: + "200": + description: The account has been deactivated. + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - success + - no-support + description: |- + An indicator as to whether or not the homeserver was able to unbind + the user's 3PIDs from the identity server(s). `success` indicates + that all identifiers have been unbound from the identity server while + `no-support` indicates that one or more identifiers failed to unbind + due to the identity server refusing the request or the homeserver + being unable to determine an identity server to unbind from. This + must be `success` if the homeserver has no identifiers to unbind + for the user. + example: success + required: + - id_server_unbind_result + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer diff --git a/data/api/client-server/password_management.yaml b/data/api/client-server/password_management.yaml new file mode 100644 index 00000000..bf310ff9 --- /dev/null +++ b/data/api/client-server/password_management.yaml @@ -0,0 +1,242 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2022 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server Password Management API + version: 1.0.0 +paths: + /account/password: + post: + summary: Changes a user's password. + description: |- + Changes the password for an account on this homeserver. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to + ensure the user changing the password is actually the owner of the + account. + + An access token should be submitted to this endpoint if the client has + an active session. + + The homeserver may change the flows available depending on whether a + valid access token is provided. The homeserver SHOULD NOT revoke the + access token provided in the request. Whether other access tokens for + the user are revoked depends on the request parameters. + security: + - {} + - accessTokenQuery: [] + - accessTokenBearer: [] + operationId: changePassword + requestBody: + content: + application/json: + schema: + type: object + properties: + new_password: + type: string + description: The new password for the account. + example: ihatebananas + logout_devices: + type: boolean + description: |- + Whether the user's other access tokens, and their associated devices, should be + revoked if the request succeeds. Defaults to true. + + When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) + for the user's remaining devices. + example: true + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: + - new_password + required: true + responses: + "200": + description: The password has been changed. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Account management + /account/password/email/requestToken: + post: + summary: Requests a validation token be sent to the given email address for the + purpose of resetting a user's password + description: |- + The homeserver must check that the given email address **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + `/account/password` endpoint. + + This API's parameters and response are identical to that of the + [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) + endpoint, except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given email address could be found. The server may instead send an + email to the given address prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. + + The homeserver should validate the email itself, either by sending a + validation email itself or by using a service it has control over. + operationId: requestTokenToResetPasswordEmail + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true + responses: + "200": + description: An email was sent to the given address. + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": + description: |- + The referenced third-party identifier is not recognised by the + homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Email not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } + tags: + - Account management + /account/password/msisdn/requestToken: + post: + summary: Requests a validation token be sent to the given phone number for the + purpose of resetting a user's password. + description: |- + The homeserver must check that the given phone number **is + associated** with an account on this homeserver. This API should be + used to request validation tokens when authenticating for the + `/account/password` endpoint. + + This API's parameters and response are identical to that of the + [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + endpoint, except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given phone number could be found. The server may instead send the SMS + to the given phone number prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. + + The homeserver should validate the phone number itself, either by sending a + validation message itself or by using a service it has control over. + operationId: requestTokenToResetPasswordMSISDN + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true + responses: + "200": + description: An SMS message was sent to the given phone number. + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": + description: |- + The referenced third-party identifier is not recognised by the + homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + can be returned if the server does not trust/support the identity server + provided in the request. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Phone number not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } + tags: + - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index a418d2d2..e7ede561 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -373,315 +373,6 @@ paths: } tags: - Account management - /account/password: - post: - summary: Changes a user's password. - description: |- - Changes the password for an account on this homeserver. - - This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to - ensure the user changing the password is actually the owner of the - account. - - An access token should be submitted to this endpoint if the client has - an active session. - - The homeserver may change the flows available depending on whether a - valid access token is provided. The homeserver SHOULD NOT revoke the - access token provided in the request. Whether other access tokens for - the user are revoked depends on the request parameters. - security: - - {} - - accessTokenQuery: [] - - accessTokenBearer: [] - operationId: changePassword - requestBody: - content: - application/json: - schema: - type: object - properties: - new_password: - type: string - description: The new password for the account. - example: ihatebananas - logout_devices: - type: boolean - description: |- - Whether the user's other access tokens, and their associated devices, should be - revoked if the request succeeds. Defaults to true. - - When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) - for the user's remaining devices. - example: true - auth: - description: Additional authentication information for the user-interactive - authentication API. - allOf: - - $ref: definitions/auth_data.yaml - required: - - new_password - required: true - responses: - "200": - description: The password has been changed. - content: - application/json: - schema: - type: object - examples: - response: - value: {} - "401": - description: The homeserver requires additional authentication information. - content: - application/json: - schema: - $ref: definitions/auth_response.yaml - "429": - description: This request was rate-limited. - content: - application/json: - schema: - $ref: definitions/errors/rate_limited.yaml - tags: - - Account management - /account/password/email/requestToken: - post: - summary: Requests a validation token be sent to the given email address for the - purpose of resetting a user's password - description: |- - The homeserver must check that the given email address **is - associated** with an account on this homeserver. This API should be - used to request validation tokens when authenticating for the - `/account/password` endpoint. - - This API's parameters and response are identical to that of the - [`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken) - endpoint, except that - `M_THREEPID_NOT_FOUND` may be returned if no account matching the - given email address could be found. The server may instead send an - email to the given address prompting the user to create an account. - `M_THREEPID_IN_USE` may not be returned. - - The homeserver should validate the email itself, either by sending a - validation email itself or by using a service it has control over. - operationId: requestTokenToResetPasswordEmail - requestBody: - content: - application/json: - schema: - $ref: definitions/request_email_validation.yaml - required: true - responses: - "200": - description: An email was sent to the given address. - content: - application/json: - schema: - $ref: definitions/request_token_response.yaml - "400": - description: |- - The referenced third-party identifier is not recognised by the - homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` - can be returned if the server does not trust/support the identity server - provided in the request. - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Email not found" - } - "403": - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - tags: - - Account management - /account/password/msisdn/requestToken: - post: - summary: Requests a validation token be sent to the given phone number for the - purpose of resetting a user's password. - description: |- - The homeserver must check that the given phone number **is - associated** with an account on this homeserver. This API should be - used to request validation tokens when authenticating for the - `/account/password` endpoint. - - This API's parameters and response are identical to that of the - [`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) - endpoint, except that - `M_THREEPID_NOT_FOUND` may be returned if no account matching the - given phone number could be found. The server may instead send the SMS - to the given phone number prompting the user to create an account. - `M_THREEPID_IN_USE` may not be returned. - - The homeserver should validate the phone number itself, either by sending a - validation message itself or by using a service it has control over. - operationId: requestTokenToResetPasswordMSISDN - requestBody: - content: - application/json: - schema: - $ref: definitions/request_msisdn_validation.yaml - required: true - responses: - "200": - description: An SMS message was sent to the given phone number. - content: - application/json: - schema: - $ref: definitions/request_token_response.yaml - "400": - description: |- - The referenced third-party identifier is not recognised by the - homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` - can be returned if the server does not trust/support the identity server - provided in the request. - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Phone number not found" - } - "403": - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - tags: - - Account management - /account/deactivate: - post: - summary: Deactivate a user's account. - description: |- - Deactivate the user's account, removing all ability for the user to - login again. - - This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - - An access token should be submitted to this endpoint if the client has - an active session. - - The homeserver may change the flows available depending on whether a - valid access token is provided. - - Unlike other endpoints, this endpoint does not take an `id_access_token` - parameter because the homeserver is expected to sign the request to the - identity server instead. - security: - - {} - - accessTokenQuery: [] - - accessTokenBearer: [] - operationId: deactivateAccount - requestBody: - content: - application/json: - schema: - type: object - properties: - auth: - description: Additional authentication information for the user-interactive - authentication API. - allOf: - - $ref: definitions/auth_data.yaml - id_server: - type: string - description: |- - The identity server to unbind all of the user's 3PIDs from. - If not provided, the homeserver MUST use the `id_server` - that was originally use to bind each identifier. If the - homeserver does not know which `id_server` that was, - it must return an `id_server_unbind_result` of - `no-support`. - example: example.org - erase: - x-addedInMatrixVersion: "1.10" - type: boolean - description: |- - Whether the user would like their content to be erased as - much as possible from the server. - - Erasure means that any users (or servers) which join the - room after the erasure request are served redacted copies of - the events sent by this account. Users which had visibility - on those events prior to the erasure are still able to see - unredacted copies. No redactions are sent and the erasure - request is not shared over federation, so other servers - might still serve unredacted copies. - - The server should additionally erase any non-event data - associated with the user, such as [account data](/client-server-api/#client-config) - and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information). - - Defaults to `false` if not present. - required: true - responses: - "200": - description: The account has been deactivated. - content: - application/json: - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - - success - - no-support - description: |- - An indicator as to whether or not the homeserver was able to unbind - the user's 3PIDs from the identity server(s). `success` indicates - that all identifiers have been unbound from the identity server while - `no-support` indicates that one or more identifiers failed to unbind - due to the identity server refusing the request or the homeserver - being unable to determine an identity server to unbind from. This - must be `success` if the homeserver has no identifiers to unbind - for the user. - example: success - required: - - id_server_unbind_result - "401": - description: The homeserver requires additional authentication information. - content: - application/json: - schema: - $ref: definitions/auth_response.yaml - "429": - description: This request was rate-limited. - content: - application/json: - schema: - $ref: definitions/errors/rate_limited.yaml - tags: - - Account management /register/available: get: summary: Checks to see if a username is available on the server. From 4e51949ad6d7ef945cfe595f2e763b00b8d573af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 14 May 2025 13:06:39 +0200 Subject: [PATCH 2/7] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2141.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2141.clarification diff --git a/changelogs/client_server/newsfragments/2141.clarification b/changelogs/client_server/newsfragments/2141.clarification new file mode 100644 index 00000000..a9df7184 --- /dev/null +++ b/changelogs/client_server/newsfragments/2141.clarification @@ -0,0 +1 @@ +Split account registration and management section and OpenAPI definitions. From c68a87cdedd59574a4de46f4da002f59318d6e0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 14 May 2025 13:11:52 +0200 Subject: [PATCH 3/7] Fix links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4933eb20..d3a71a70 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -439,7 +439,7 @@ endpoints it supports. Most API endpoints require the user to identify themselves by presenting previously obtained credentials in the form of an access token. An access token is typically obtained via the [Login](#login) or -[Registration](#account-registration-and-management) processes. Access tokens +[Registration](#account-registration) processes. Access tokens can expire; a new access token can be generated by using a refresh token. {{% boxes/note %}} @@ -494,7 +494,7 @@ used to generate a new access token and refresh token, the new access and refresh tokens are now bound to the device associated with the initial refresh token. -By default, the [Login](#login) and [Registration](#account-registration-and-management) +By default, the [Login](#login) and [Registration](#account-registration) processes auto-generate a new `device_id`. A client is also free to generate its own `device_id` or, provided the user remains the same, reuse a device: in either case the client should pass the `device_id` in From 698df60bd5588c0efe81a346e92a96ea3798d7ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 24 May 2025 15:17:43 +0200 Subject: [PATCH 4/7] Add parent sections of Legacy API and OAuth 2.0 API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 56 +++++++++++++++-------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d3a71a70..38a84a7d 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -560,9 +560,11 @@ specifying the device ID it is already using to the login API. with an `M_USER_LOCKED` error code, cannot obtain a new access token until the account has been [unlocked](#account-locking). -### User-Interactive Authentication API +### Legacy API -#### Overview +#### User-Interactive Authentication API + +##### Overview Some API endpoints require authentication that interacts with the user. The homeserver may provide many different ways of authenticating, such @@ -586,7 +588,7 @@ the flows in order must result in an HTTP 401 response, as defined below. When all stages in a flow are complete, authentication is complete and the API call succeeds. -#### User-interactive API in the REST API +##### User-interactive API in the REST API In the REST API described in this specification, authentication works by the client and server exchanging JSON dictionaries. The server indicates @@ -764,7 +766,7 @@ auth by offering a stage with only the `m.login.dummy` auth type, but they must still give a 401 response to requests with no auth data. {{% /boxes/note %}} -#### Example +**Example** At a high level, the requests made for an API call completing an auth flow with three stages will resemble the following diagram: @@ -806,7 +808,7 @@ flow with three stages will resemble the following diagram: |_______________________| ``` -#### Authentication types +##### Authentication types This specification defines the following auth types: - `m.login.password` @@ -817,7 +819,7 @@ This specification defines the following auth types: - `m.login.dummy` - `m.login.registration_token` -##### Password-based +###### Password-based | Type | Description | @@ -876,7 +878,7 @@ explicitly as follows: In the case that the homeserver does not know about the supplied 3PID, the homeserver must respond with 403 Forbidden. -##### Google ReCaptcha +###### Google ReCaptcha | Type | Description | |---------------------|------------------------------------------------------| @@ -893,7 +895,7 @@ follows: } ``` -##### Single Sign-On +###### Single Sign-On | Type | Description | |---------------|--------------------------------------------------------------------------------------| @@ -903,7 +905,7 @@ A client wanting to complete authentication using SSO should use the [Fallback](#fallback) mechanism. See [SSO during User-Interactive Authentication](#sso-during-user-interactive-authentication) for more information. -##### Email-based (identity / homeserver) +###### Email-based (identity / homeserver) | Type | Description | |--------------------------|------------------------------------------------------------------------------------------------------------------| @@ -932,7 +934,7 @@ follows: Note that `id_server` (and therefore `id_access_token`) is optional if the [`/requestToken`](#post_matrixclientv3registeremailrequesttoken) request did not include them. -##### Phone number/MSISDN-based (identity / homeserver) +###### Phone number/MSISDN-based (identity / homeserver) | Type | Description | |------------------|----------------------------------------------------------------------------------------------------------------| @@ -961,7 +963,7 @@ follows: Note that `id_server` (and therefore `id_access_token`) is optional if the [`/requestToken`](#post_matrixclientv3registermsisdnrequesttoken) request did not include them. -##### Dummy Auth +###### Dummy Auth | Type | Description | |------------------|------------------------------------------------------------------------| @@ -987,7 +989,7 @@ just the type and session, if provided: } ``` -##### Token-authenticated registration +###### Token-authenticated registration {{% added-in v="1.2" %}} @@ -1031,7 +1033,7 @@ in the registration process that their token has expired. {{% http-api spec="client-server" api="registration_tokens" %}} -##### Terms of service at registration +###### Terms of service at registration {{% added-in v="1.11" %}} @@ -1154,7 +1156,7 @@ user during registration, if applicable. {{% definition path="api/client-server/definitions/m.login.terms_params" %}} -#### Fallback +##### Fallback Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login @@ -1195,7 +1197,7 @@ with just the session ID: } ``` -##### Example +**Example** A client webapp might use the following JavaScript to open a popup window which will handle unknown login types: @@ -1251,7 +1253,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo } ``` -#### Identifier types +##### Identifier types Some authentication mechanisms use a user identifier object to identify a user. The user identifier object has a `type` field to indicate the @@ -1264,7 +1266,7 @@ This specification defines the following identifier types: - `m.id.thirdparty` - `m.id.phone` -##### Matrix User ID +###### Matrix User ID | Type | Description | |-------------|--------------------------------------------| @@ -1281,7 +1283,7 @@ ID. } ``` -##### Third-party ID +###### Third-party ID | Type | Description | |-------------------|---------------------------------------------------------------------------| @@ -1301,7 +1303,7 @@ ID media. } ``` -##### Phone number +###### Phone number | Type | Description | |--------------|-------------------------------------------| @@ -1327,7 +1329,7 @@ The `country` is the two-letter uppercase ISO-3166-1 alpha-2 country code that the number in `phone` should be parsed as if it were dialled from. -### Login +#### Login A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API. @@ -1399,7 +1401,7 @@ a token for their user ID if supported by the homeserver using {{% http-api spec="client-server" api="logout" %}} -#### Appservice Login +##### Appservice Login {{% added-in v="1.2" %}} @@ -1436,7 +1438,7 @@ If the access token does correspond to an appservice, but the user id does not lie within its namespace then the homeserver will respond with an errcode of `M_EXCLUSIVE`. -#### Login Fallback +##### Login Fallback If a client does not recognize any or all login flows it can use the fallback login API: @@ -1456,13 +1458,13 @@ forwarded to the login endpoint during the login process. For example: GET /_matrix/static/client/login/?device_id=GHTYAJCE -### Account registration +#### Account registration {{% http-api spec="client-server" api="registration" %}} -### Account management +#### Account management -#### Password management +##### Password management {{% boxes/warning %}} Clients SHOULD enforce that the password provided is suitably complex. @@ -1473,10 +1475,12 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% http-api spec="client-server" api="password_management" %}} -#### Account deactivation +##### Account deactivation {{% http-api spec="client-server" api="account_deactivation" %}} +### OAuth 2.0 API + ### Account moderation #### Account locking From 687e8c3c2251d69648f11559d7c38058511299af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 24 May 2025 15:25:35 +0200 Subject: [PATCH 5/7] Update changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2141.clarification | 1 - changelogs/client_server/newsfragments/2141.feature | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 changelogs/client_server/newsfragments/2141.clarification create mode 100644 changelogs/client_server/newsfragments/2141.feature diff --git a/changelogs/client_server/newsfragments/2141.clarification b/changelogs/client_server/newsfragments/2141.clarification deleted file mode 100644 index a9df7184..00000000 --- a/changelogs/client_server/newsfragments/2141.clarification +++ /dev/null @@ -1 +0,0 @@ -Split account registration and management section and OpenAPI definitions. diff --git a/changelogs/client_server/newsfragments/2141.feature b/changelogs/client_server/newsfragments/2141.feature new file mode 100644 index 00000000..6eff5607 --- /dev/null +++ b/changelogs/client_server/newsfragments/2141.feature @@ -0,0 +1 @@ +Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals. From 0fe1801c62638b0b15b695c862a1f16bea79d86d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sun, 25 May 2025 11:46:58 +0200 Subject: [PATCH 6/7] Add OAuth 2.0 scopes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2967 Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 90 +++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 38a84a7d..58f5d8d0 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1481,6 +1481,96 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. ### OAuth 2.0 API +#### Scope + +The client requests a scope in the OAuth 2.0 authorization flow, which is then +associated to the generated access and refresh tokens. This provides a framework +for obtaining user consent. + +A scope is defined in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) +as a string containing a list of space-separated scope tokens. + +{{% boxes/note %}} +The framework encourages the practice of obtaining additional user consent when +a client asks for a new scope that was not granted previously. This could be +used by future MSCs to replace the legacy [User-Interactive Authentication API](#user-interactive-authentication-api). +{{% /boxes/note %}} + +##### Scope token format + +All scope tokens related to Matrix should start with `urn:matrix:` and use the +`:` delimiter for further sub-division. + +Scope tokens related to mapping of Client-Server API access levels should start +with `urn:matrix:client:`. + +{{% boxes/note %}} +For MSCs that build on this namespace, unstable subdivisions should be used +whilst in development. For example, if MSCXXXX wants to introduce the +`urn:matrix:client:foo` scope, it could use +`urn:matrix:client:com.example.mscXXXX.foo` during development. +If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and +`urn:matrix:client:bar`, it could use +`urn:matrix:client:com.example.mscXXXX:foo` and +`urn:matrix:client:com.example.mscXXXX:bar`. +{{% /boxes/note %}} + +##### Allocated scope tokens + +This specification defines the following scope tokens: +- [`urn:matrix:client:api:*`](#full-client-server-api-readwrite-access) +- [`urn:matrix:client:device:`](#device-id-allocation) + +###### Full client-server API read/write access + +| Scope | Purpose | +|---------------------------|---------------------------------------------| +| `urn:matrix:client:api:*` | Grants full access to the Client-Server API | + +{{% boxes/note %}} +This token matches the behavior of the legacy authentication API. Future MSCs +could introduce more fine-grained scope tokens like +`urn:matrix:client:api:read:*` for read-only access. +{{% /boxes/note %}} + +###### Device ID allocation + +| Scope | Purpose | +|----------------------------------------|----------------------------------------------------------------------------------------------| +| `urn:matrix:client:device:` | Allocates the given `device_id` and associates it to the generated access and refresh tokens | + +Contrary to the legacy login and registration APIs where the homeserver is +typically the one generating a `device_id` and providing it to the client, with +the OAuth 2.0 API, the client is responsible for allocating the `device_id`. + +There MUST be exactly one `urn:matrix:client:device:` token in the +requested scope in the login flow. + +When generating a new `device_id`, the client SHOULD generate a random string +with enough entropy. It SHOULD only use characters from the unreserved character +list defined by [RFC 3986 section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3): + +``` +unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~" +``` + +Using this alphabet, a 10 character string is enough to stand a sufficient +chance of being unique per user. The homeserver MAY reject a request for a +`device_id` that is not long enough or contains characters outside the +unreserved list. + +In any case it MUST only use characters allowed by the OAuth 2.0 scope +definition in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3), +which is defined as the following ASCII ranges: + +``` +%x21 / %x23-5B / %x5D-7E +``` + +This definition matches: +- alphanumeric characters: `A-Z`, `a-z`, `0-9` +- the following characters: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~`` + ### Account moderation #### Account locking From d60e7bfe2614b58537459a52df19162c1ef111b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sun, 25 May 2025 11:49:57 +0200 Subject: [PATCH 7/7] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2149.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2149.feature diff --git a/changelogs/client_server/newsfragments/2149.feature b/changelogs/client_server/newsfragments/2149.feature new file mode 100644 index 00000000..6eff5607 --- /dev/null +++ b/changelogs/client_server/newsfragments/2149.feature @@ -0,0 +1 @@ +Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.