From e5ad585bfdd9b5125de17c129710a5c9adf4248f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 21 Jan 2026 10:01:23 +0100 Subject: [PATCH] Apply suggestions 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 | 24 ++++++++----------- .../definitions/sso_login_flow.yaml | 5 ++-- data/api/client-server/registration.yaml | 5 ++-- .../api/client-server/sso_login_redirect.yaml | 6 ++--- 4 files changed, 18 insertions(+), 22 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9cc3aba6..6f680fde 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -482,9 +482,9 @@ such as automated applications that cannot use a web browser. {{% boxes/note %}} {{% 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). +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 @@ -1525,11 +1525,6 @@ 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.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. - {{% 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). @@ -1628,10 +1623,11 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% 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 -to implement the full OAuth 2.0 API. +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 @@ -1639,8 +1635,8 @@ 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 + 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. diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 714cbcab..18c32054 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -90,8 +90,9 @@ properties: type: boolean 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). + 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/registration.yaml b/data/api/client-server/registration.yaml index 25c6bf4a..acb0b135 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -77,8 +77,9 @@ paths: {{% 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 - `action=register` parameter to the SSO redirect endpoint. + `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: diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index ec110aa7..2276eb70 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -41,8 +41,7 @@ paths: name: action 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). + 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 @@ -96,8 +95,7 @@ paths: name: action 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). + 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