From f5859110e2b8a4519b2167a46330ef7a51051ee9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 17 Dec 2025 12:04:39 +0100 Subject: [PATCH 1/6] Spec OAuth 2.0 aware clients MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC3824. Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 71 +++++++++++++++++++ .../definitions/sso_login_flow.yaml | 7 ++ .../api/client-server/sso_login_redirect.yaml | 34 +++++++++ 3 files changed, 112 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2460776f1..58f23d9db 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -481,6 +481,13 @@ such as automated applications that cannot use a web browser, or user management by [application services](application-service-api/#server-admin-style-permissions). {{% /boxes/note %}} +{{% boxes/note %}} +{{% added-in v="1.17" %}} +A compatibility layer is available to ease the transition from the legacy API to +the OAuth 2.0 API for clients that only support the legacy API called [OAuth 2.0 +aware clients](#oauth-20-aware-clients). +{{% /boxes/note %}} + ### Authentication API discovery To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login) @@ -1603,6 +1610,70 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% http-api spec="client-server" api="account_deactivation" %}} +#### OAuth 2.0 aware clients + +This is a compatibility layer that allows clients that only support the legacy +API to make some less-invasive changes to improve the user experience when +talking to a homeserver that is using the OAuth 2.0 API without actually having +to implement the full OAuth 2.0 API. + +##### Client behaviour + +For a client to be considered fully OAuth 2.0 aware it MUST: + +* Support the [`m.login.sso` authentication flow](#client-login-via-sso). +* Where a `oauth_aware_preferred` value of `true` is present on an `m.login.sso` + flow then *only* offer that auth flow to the user. +* Append `action=login` and `action=register` parameters to the [SSO redirect + endpoints](#get_matrixclientv3loginssoredirect). The client might determine + the value to use based on whether the user clicked a "Login" or "Register" + button. +* Check and honour the [`m.3pid_changes` capability](#m3pid_changes-capability) + so that the user is not offered the ability to add or remove 3PIDs if the + homeserver says the capability is not available. +* Determine if the homeserver is using the OAuth 2.0 API by using + [server metadata discovery](#get_matrixclientv1auth_metadata) from the OAuth + 2.0 API. +* If a homeserver is using the OAuth 2.0 API as discovered in the previous step + then the client MUST redirect users to manage their account at the [account + management URL](#oauth-20-account-management), if available, instead of + providing a native UI using the legacy API endpoints. + + * If the user wishes to deactivate their account then the client MUST refer + them to the account management URL. + * If the user wishes to sign out a device other than its own then the client + MUST deep link the user to the account management URL by adding the + `action=org.matrix.device_delete` and `device_id=` parameters so + that the web UI knows that the user wishes to sign out a device and which + one it is. + +Optionally, an OAuth 2.0 aware client COULD: + +* Label the SSO button as "Continue" rather than "SSO" when + `oauth_aware_preferred` is `true`. This is because after redirect the server + may then offer a password and/or further upstream IdPs. +* Pass other [account management URL parameters](#account-management-url-parameters) + for context when linking to the account web UI. + +##### Server behaviour + +For a homeserver to provide support for OAuth 2.0 aware clients it MUST: + +* Support the [OAuth 2.0 API](#oauth-20-api). +* Provide an implementation of the [`m.login.sso` authentication flow](#client-login-via-sso) + from the legacy API. +* If password authentication was previously enabled on the homeserver then + provide an implementation of the [`m.login.password` authentication flow](#legacy-login) + from the legacy API. +* Indicate that the `m.login.sso` flow is preferred by setting + `oauth_aware_preferred` to `true`. +* Support a value for the `action` param on the [SSO redirect endpoints](#get_matrixclientv3loginssoredirect). + +Additionally, the homeserver SHOULD: + +* Advertise the [account management URL](#oauth-20-account-management) in the + [server metadata](#get_matrixclientv1auth_metadata). + ### OAuth 2.0 API {{% added-in v="1.15" %}} diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 0996511eb..2f395c3a0 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -86,5 +86,12 @@ properties: brand usage as intended by the server. example: "github" required: ['id', 'name'] + oauth_aware_preferred: + type: bool + x-addedInMatrixVersion: "1.17" + description: | + Whether the `m.login.sso` flow is preferred over other flows for + [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients). + example: true required: ['type'] diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 9f9d758bc..c9ab99b90 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -37,6 +37,23 @@ paths: required: true schema: type: string + - in: query + name: action + x-addedInMatrixVersion: "1.17" + description: |- + The action that the user wishes to take at the SSO redirect, for + [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients). + + The following values are supported: + * `login`: the SSO redirect is for the purposes of signing an + existing user in. + * `register`: the SSO redirect is for the purpose of registering a + new user account. + schema: + type: string + enum: + - login + - register responses: "302": description: A redirect to the SSO interface. @@ -75,6 +92,23 @@ paths: required: true schema: type: string + - in: query + name: action + x-addedInMatrixVersion: "1.17" + description: |- + The action that the user wishes to take at the SSO redirect, for + [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients). + + The following values are supported: + * `login`: the SSO redirect is for the purposes of signing an + existing user in. + * `register`: the SSO redirect is for the purpose of registering a + new user account. + schema: + type: string + enum: + - login + - register responses: "302": description: A redirect to the SSO interface. From 6eb041804ade5fd8ae724a77409fc518dabd9735 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 17 Dec 2025 12:07:09 +0100 Subject: [PATCH 2/6] 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/2272.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2272.feature diff --git a/changelogs/client_server/newsfragments/2272.feature b/changelogs/client_server/newsfragments/2272.feature new file mode 100644 index 000000000..34b6a493e --- /dev/null +++ b/changelogs/client_server/newsfragments/2272.feature @@ -0,0 +1 @@ +Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824). From 052806e192127b0aac6ab87e60b5cfd47b9ed6d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 17 Dec 2025 12:08:56 +0100 Subject: [PATCH 3/6] Fix JSON schema type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/definitions/sso_login_flow.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 2f395c3a0..28d173a00 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -87,7 +87,7 @@ properties: example: "github" required: ['id', 'name'] oauth_aware_preferred: - type: bool + type: boolean x-addedInMatrixVersion: "1.17" description: | Whether the `m.login.sso` flow is preferred over other flows for From 839fd19b1ae2f26a078a38a589ce92ee38197d8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 18 Dec 2025 10:01:02 +0100 Subject: [PATCH 4/6] Change COULD to MAY 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 58f23d9db..64b1ee015 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1647,7 +1647,7 @@ For a client to be considered fully OAuth 2.0 aware it MUST: that the web UI knows that the user wishes to sign out a device and which one it is. -Optionally, an OAuth 2.0 aware client COULD: +Optionally, an OAuth 2.0 aware client MAY: * Label the SSO button as "Continue" rather than "SSO" when `oauth_aware_preferred` is `true`. This is because after redirect the server From adcd6ba4a2b607454fb594004548f54e391cb2c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 18 Dec 2025 10:37:12 +0100 Subject: [PATCH 5/6] Add instructions on endpoints that should no longer be used 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 | 5 +++++ data/api/client-server/account_deactivation.yaml | 8 ++++++++ data/api/client-server/device_management.yaml | 14 ++++++++++++++ data/api/client-server/registration.yaml | 8 ++++++++ 4 files changed, 35 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 64b1ee015..82aeaac80 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1520,6 +1520,11 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. +{{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) +MUST only offer the `m.login.sso` flow to the user when `oauth_aware_preferred` +is set to `true` and MUST add the `action=login` parameter to the SSO redirect +endpoint. + {{% added-in v="1.7" %}} Already-authenticated clients can additionally generate a token for their user ID if supported by the homeserver using [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml index 467af659a..c7f68f67f 100644 --- a/data/api/client-server/account_deactivation.yaml +++ b/data/api/client-server/account_deactivation.yaml @@ -35,6 +35,14 @@ paths: 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. + + {{% boxes/warning %}} + {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available, and MAY use the `action=org.matrix.account_deactivate` + parameter. + {{% /boxes/warning %}} security: - {} - accessTokenQuery: [] diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 1b245e78d..da54c111f 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -142,6 +142,13 @@ paths: 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 %}} + + {{% boxes/warning %}} + {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters. + {{% /boxes/warning %}} operationId: deleteDevice security: - accessTokenQuery: [] @@ -199,6 +206,13 @@ paths: 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 %}} + + {{% boxes/warning %}} + {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available. + {{% /boxes/warning %}} operationId: deleteDevices security: - accessTokenQuery: [] diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index e7ede5616..535689da4 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -60,6 +60,14 @@ paths: Any user ID returned by this API must conform to the grammar given in the [Matrix specification](/appendices/#user-identifiers). + + {{% boxes/warning %}} + {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server offers the [`m.login.sso` + authentication flow](/client-server-api/#client-login-via-sso) with + `oauth_aware_preferred` set to `true`. Instead they MUST add the + `action=register` parameter to the SSO redirect endpoint. + {{% /boxes/warning %}} operationId: register parameters: - in: query From 5541bf14178ddfd5258b14badb76296cbd4e68a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Fri, 19 Dec 2025 10:35:09 +0100 Subject: [PATCH 6/6] Bump Matrix version 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 | 6 ++++-- data/api/client-server/account_deactivation.yaml | 2 +- data/api/client-server/definitions/sso_login_flow.yaml | 2 +- data/api/client-server/device_management.yaml | 4 ++-- data/api/client-server/registration.yaml | 2 +- data/api/client-server/sso_login_redirect.yaml | 4 ++-- 6 files changed, 11 insertions(+), 9 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 82aeaac80..5a611587e 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -482,7 +482,7 @@ user management by [application services](application-service-api/#server-admin- {{% /boxes/note %}} {{% boxes/note %}} -{{% added-in v="1.17" %}} +{{% added-in v="1.18" %}} A compatibility layer is available to ease the transition from the legacy API to the OAuth 2.0 API for clients that only support the legacy API called [OAuth 2.0 aware clients](#oauth-20-aware-clients). @@ -1520,7 +1520,7 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. -{{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) +{{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST only offer the `m.login.sso` flow to the user when `oauth_aware_preferred` is set to `true` and MUST add the `action=login` parameter to the SSO redirect endpoint. @@ -1617,6 +1617,8 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. #### OAuth 2.0 aware clients +{{% added-in v="1.18" %}} + This is a compatibility layer that allows clients that only support the legacy API to make some less-invasive changes to improve the user experience when talking to a homeserver that is using the OAuth 2.0 API without actually having diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml index c7f68f67f..2275fdff1 100644 --- a/data/api/client-server/account_deactivation.yaml +++ b/data/api/client-server/account_deactivation.yaml @@ -37,7 +37,7 @@ paths: identity server instead. {{% boxes/warning %}} - {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), if available, and MAY use the `action=org.matrix.account_deactivate` diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 28d173a00..714cbcab9 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -88,7 +88,7 @@ properties: required: ['id', 'name'] oauth_aware_preferred: type: boolean - x-addedInMatrixVersion: "1.17" + x-addedInMatrixVersion: "1.18" description: | Whether the `m.login.sso` flow is preferred over other flows for [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients). diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index da54c111f..1f66f8565 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -144,7 +144,7 @@ paths: {{% /boxes/warning %}} {{% boxes/warning %}} - {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters. @@ -208,7 +208,7 @@ paths: {{% /boxes/warning %}} {{% boxes/warning %}} - {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), if available. diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 535689da4..0e88870ac 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -62,7 +62,7 @@ paths: [Matrix specification](/appendices/#user-identifiers). {{% boxes/warning %}} - {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST NOT use this endpoint when the server offers the [`m.login.sso` authentication flow](/client-server-api/#client-login-via-sso) with `oauth_aware_preferred` set to `true`. Instead they MUST add the diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index c9ab99b90..ec110aa79 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -39,7 +39,7 @@ paths: type: string - in: query name: action - x-addedInMatrixVersion: "1.17" + x-addedInMatrixVersion: "1.18" description: |- The action that the user wishes to take at the SSO redirect, for [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients). @@ -94,7 +94,7 @@ paths: type: string - in: query name: action - x-addedInMatrixVersion: "1.17" + x-addedInMatrixVersion: "1.18" description: |- The action that the user wishes to take at the SSO redirect, for [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).