From 1c06ed9cf77c56094ab7ee43f86a7e7fb6e61654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 26 Jun 2025 18:40:43 +0200 Subject: [PATCH] Final tweaks for the OAuth 2.0 API (#2164) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Clarify that SSO login applies to the legacy authentication API Signed-off-by: Kévin Commaille * Do not point to specific authentication API for obtaining access token Signed-off-by: Kévin Commaille * Add warnings about incompatibility with OAuth 2.0 to endpoints that use UIA Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Add note about API standards not applying to OAuth 2.0 Signed-off-by: Kévin Commaille * Apply suggestions from code review --------- Signed-off-by: Kévin Commaille Co-authored-by: Travis Ralston --- changelogs/client_server/newsfragments/2164.feature | 1 + content/client-server-api/_index.md | 6 ++++++ content/client-server-api/modules/sso_login.md | 9 +++++---- data/api/client-server/administrative_contact.yaml | 5 +++++ data/api/client-server/cross_signing.yaml | 11 ++++++++--- data/api/client-server/definitions/security.yaml | 12 ++++++------ data/api/client-server/device_management.yaml | 10 ++++++++++ 7 files changed, 41 insertions(+), 13 deletions(-) create mode 100644 changelogs/client_server/newsfragments/2164.feature diff --git a/changelogs/client_server/newsfragments/2164.feature b/changelogs/client_server/newsfragments/2164.feature new file mode 100644 index 00000000..6eff5607 --- /dev/null +++ b/changelogs/client_server/newsfragments/2164.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. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index fbf678a6..e7de10eb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -12,6 +12,12 @@ clients which maintain a full local persistent copy of server state. ## API Standards +{{% boxes/note %}} +These standards only apply to the APIs defined in the Matrix specification. APIs +used by this specification but defined in other specifications, like the [OAuth +2.0 API](#oauth-20-api), use their own rules. +{{% /boxes/note %}} + The mandatory baseline for client-server communication in Matrix is exchanging JSON objects over HTTP APIs. More efficient transports may be specified in future as optional extensions. diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index f50a2eb1..8b228356 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -6,9 +6,10 @@ allow users to log into applications via a single web-based authentication portal. Examples include OpenID Connect, "Central Authentication Service" (CAS) and SAML. -This module allows a Matrix homeserver to delegate user authentication -to an external authentication server supporting one of these protocols. -In this process, there are three systems involved: +This module allows a Matrix homeserver that supports the [legacy authentication +API](#legacy-api) to delegate user authentication to an external authentication +server supporting one of these protocols. In this process, there are three +systems involved: - A Matrix client, using the APIs defined in this specification, which is seeking to authenticate a user to a Matrix homeserver. @@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix homeserver implementations might support different SSO protocols. Clients and homeservers implementing the SSO flow will need to consider -both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is +both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is similar in both cases, but there are slight differences. Typically, SSO systems require a single "callback" URI to be configured diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index eddb2b01..54b91d42 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -201,6 +201,11 @@ paths: Homeservers should prevent the caller from adding a 3PID to their account if it has already been added to another user's account on the homeserver. + + {{% boxes/warning %}} + Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained + via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + {{% /boxes/warning %}} operationId: add3PID security: - accessTokenQuery: [] diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 8f499d23..60fa9e5b 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -26,7 +26,7 @@ paths: Publishes cross-signing keys for the user. This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - + User-Interactive Authentication MUST be performed, except in these cases: - there is no existing cross-signing master key uploaded to the homeserver, OR - there is an existing cross-signing master key and it exactly matches the @@ -34,11 +34,16 @@ paths: keys provided in the request (self-signing key, user-signing key) they MUST also match the existing keys stored on the server. In other words, the request contains no new keys. - + This allows clients to freely upload one set of keys, but not modify/overwrite keys if - they already exist. Allowing clients to upload the same set of keys more than once + they already exist. Allowing clients to upload the same set of keys more than once makes this endpoint idempotent in the case where the response is lost over the network, which would otherwise cause a UIA challenge upon retry. + + {{% boxes/warning %}} + When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained + via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + {{% /boxes/warning %}} operationId: uploadCrossSigningKeys security: - accessTokenQuery: [] diff --git a/data/api/client-server/definitions/security.yaml b/data/api/client-server/definitions/security.yaml index 0c9bd1c7..bb84a08c 100644 --- a/data/api/client-server/definitions/security.yaml +++ b/data/api/client-server/definitions/security.yaml @@ -14,8 +14,8 @@ accessTokenQuery: type: apiKey description: |- - **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query - parameter. + **Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration) + or [login](/client-server-api/#login), as a query parameter. It can also be the `as_token` of an application service. name: access_token @@ -23,11 +23,11 @@ accessTokenQuery: accessTokenBearer: type: http description: |- - The `access_token` returned by a call to `/login` or `/register`, using the - `Authorization: Bearer` header. + The `access_token` obtained during [account registration](/client-server-api/#account-registration) + or [login](/client-server-api/#login), using the `Authorization: Bearer` header. It can also be the `as_token` of an application service. - + This is the preferred method. scheme: bearer appserviceAccessTokenQuery: @@ -42,6 +42,6 @@ appserviceAccessTokenBearer: description: |- The `as_token` of an application service, using the `Authorization: Bearer` header. - + This is the preferred method. scheme: bearer diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index b2bcb8ce..1b245e78 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -137,6 +137,11 @@ paths: This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). Deletes the given device, and invalidates any access token associated with it. + + {{% boxes/warning %}} + Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained + via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + {{% /boxes/warning %}} operationId: deleteDevice security: - accessTokenQuery: [] @@ -189,6 +194,11 @@ paths: This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). Deletes the given devices, and invalidates any access token associated with them. + + {{% boxes/warning %}} + Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained + via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + {{% /boxes/warning %}} operationId: deleteDevices security: - accessTokenQuery: []