diff --git a/changelogs/client_server/newsfragments/2234.feature b/changelogs/client_server/newsfragments/2234.feature new file mode 100644 index 00000000..2dd33f67 --- /dev/null +++ b/changelogs/client_server/newsfragments/2234.feature @@ -0,0 +1 @@ +Add the `m.oauth` authentication type for User-Interactive Authentication as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c4b632bb..2460776f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -907,6 +907,7 @@ This specification defines the following auth types: - `m.login.dummy` - `m.login.registration_token` - {{% added-in v="1.11" %}} `m.login.terms` +- {{% added-in v="1.17" %}} `m.oauth` ###### Password-based @@ -1245,6 +1246,40 @@ user during registration, if applicable. {{% definition path="api/client-server/definitions/m.login.terms_params" %}} +###### OAuth authentication + +{{% added-in v="1.17" %}} + +| Type | Description | +|-------------------------------|-------------------------------------------------------------------| +| `m.oauth` | Authentication is supported by authorising via the homeserver's OAuth account management web UI. | + +{{% boxes/note %}} +The `m.oauth` authentication type is currently only valid on the +[`/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload) endpoint. +{{% /boxes/note %}} + +This authentication type provides homeservers the ability to guard access to +sensitive actions when the client has authenticated via the +[OAuth 2.0 API](/client-server-api/#oauth-20-api), which is otherwise not +compatible with User-Interactive Authentication (UIA). To do so, the server +returns a 401 response on the respective request, where the response body +includes `m.oauth` in the `flows` list, and the `m.oauth` property in the +`params` object has the structure [shown below](#definition-moauth-params). + +The client is expected to open the contained URL to let the user confirm the +action in the homeserver's account management web UI. Once the user has done +so, the client submits an `auth` dict with just the `session`, as follows, +to complete the stage: + +```json +{ + "session": "" +} +``` + +{{% definition path="api/client-server/definitions/m.oauth_params" %}} + ##### Fallback Clients cannot be expected to be able to know how to process every @@ -1591,6 +1626,11 @@ because they don't have access to the user's credentials anymore. The [User-Interactive Authentication API](#user-interactive-authentication-api) is not compatible with the OAuth 2.0 API, so the endpoints that depend on it for authentication can't be used when an access token is obtained with this API. + +The only exception to this is the +[`/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload) +endpoint which uses the [`m.oauth`](/client-server-api/#oauth-authentication) +authentication type. {{% /boxes/warning %}} **Sample flow** diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 60fa9e5b..ec490b2a 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -40,10 +40,12 @@ paths: 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 + {{% boxes/note %}} + When this endpoint requires User-Interactive Authentication, + it uses the [`m.oauth`](/client-server-api/#oauth-authentication) + authentication type if the access token was obtained via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). - {{% /boxes/warning %}} + {{% /boxes/note %}} operationId: uploadCrossSigningKeys security: - accessTokenQuery: [] diff --git a/data/api/client-server/definitions/m.oauth_params.yaml b/data/api/client-server/definitions/m.oauth_params.yaml new file mode 100644 index 00000000..cf64da8e --- /dev/null +++ b/data/api/client-server/definitions/m.oauth_params.yaml @@ -0,0 +1,30 @@ +# Copyright 2025 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. + +type: object +title: m.oauth params +description: Schema for `m.oauth` entry in the `params` object in a User-Interactive Authentication response. +required: ['url'] +properties: + url: + type: string + format: uri + description: | + A URL pointing to the homeserver's OAuth account management web UI + where the user can approve the action. MUST be a valid URI with scheme + `http://` or `https://`, the latter being RECOMMENDED. + pattern: "^https?://" +example: { + "url": "https://example.org/account/reset-cross-signing" +}