From 70666945712eff975f3a1f61fd9d6554df74ed20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 21 Jan 2026 11:55:59 +0100 Subject: [PATCH] Spec for MSC3824: OAuth 2.0 aware clients (#2272) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../client_server/newsfragments/2272.feature | 1 + content/client-server-api/_index.md | 74 +++++++++++++++++++ .../client-server/account_deactivation.yaml | 8 ++ .../definitions/sso_login_flow.yaml | 8 ++ data/api/client-server/device_management.yaml | 14 ++++ data/api/client-server/registration.yaml | 9 +++ .../api/client-server/sso_login_redirect.yaml | 32 ++++++++ 7 files changed, 146 insertions(+) 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 00000000..34b6a493 --- /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). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 35311138..6f680fde 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -480,6 +480,13 @@ Currently the OAuth 2.0 API doesn't cover all the use cases of the legacy API, such as automated applications that cannot use a web browser. {{% /boxes/note %}} +{{% boxes/note %}} +{{% added-in v="1.18" %}} +A compatibility feature, called [OAuth 2.0 aware clients](#oauth-20-aware-clients), +is available to ease the transition to the OAuth 2.0 API for clients that only +support the legacy API. +{{% /boxes/note %}} + ### Authentication API discovery To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login) @@ -1612,6 +1619,73 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% http-api spec="client-server" api="account_deactivation" %}} +#### OAuth 2.0 aware clients + +{{% added-in v="1.18" %}} + +This is a compatibility feature to aide clients in the transition to the OAuth +2.0 API. It 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, *only* offer that auth flow to the user. +* Append `action=login` or `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 MAY: + +* 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/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml index 467af659..2275fdff 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.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` + parameter. + {{% /boxes/warning %}} security: - {} - accessTokenQuery: [] diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 0996511e..18c32054 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -86,5 +86,13 @@ properties: brand usage as intended by the server. example: "github" required: ['id', 'name'] + oauth_aware_preferred: + type: boolean + x-addedInMatrixVersion: "1.18" + description: | + Whether the `m.login.sso` flow is preferred over other flows. If this is `true`, + [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) MUST only + offer this flow to the user. + example: true required: ['type'] diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 94dde899..e5ae56ce 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -170,6 +170,13 @@ paths: 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 %}} + + {{% boxes/warning %}} + {{% 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. + {{% /boxes/warning %}} operationId: deleteDevice security: - accessTokenQuery: [] @@ -232,6 +239,13 @@ paths: 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 %}} + + {{% boxes/warning %}} + {{% 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. + {{% /boxes/warning %}} operationId: deleteDevices security: - accessTokenQuery: [] diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 7a923f9e..acb0b135 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -72,6 +72,15 @@ paths: `inhibit_login` parameter is not set to `true`, the server MUST return a 400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code. {{% /boxes/note %}} + + {{% boxes/warning %}} + {{% 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 use the + [`/login/sso/redirect`](/client-server-api/#get_matrixclientv3loginssoredirect) + endpoint, adding the `action=register` parameter. + {{% /boxes/warning %}} operationId: register parameters: - in: query diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 9f9d758b..2276eb70 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -37,6 +37,22 @@ paths: required: true schema: type: string + - in: query + name: action + x-addedInMatrixVersion: "1.18" + description: |- + The action that the user wishes to take at the SSO redirect. + + 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 +91,22 @@ paths: required: true schema: type: string + - in: query + name: action + x-addedInMatrixVersion: "1.18" + description: |- + The action that the user wishes to take at the SSO redirect. + + 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.