mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-05-01 22:54:10 +02:00
Compare commits
1 commit
9ac0b07b48
...
b4df0ce63a
| Author | SHA1 | Date | |
|---|---|---|---|
|
b4df0ce63a |
|
|
@ -1 +0,0 @@
|
|||
Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824).
|
||||
|
|
@ -480,13 +480,6 @@ 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)
|
||||
|
|
@ -652,7 +645,7 @@ manage their account like [changing their password](#password-management),
|
|||
[deactivating their account](#account-deactivation).
|
||||
|
||||
With the OAuth 2.0 API, all account management is done via the homeserver's web
|
||||
UI that can be accessed by users via the [account management URL](#oauth-20-account-management).
|
||||
UI.
|
||||
|
||||
### Legacy API
|
||||
|
||||
|
|
@ -1619,73 +1612,6 @@ 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=<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" %}}
|
||||
|
|
@ -2345,46 +2271,6 @@ The server SHOULD return one of the following responses:
|
|||
- For other errors, the server returns a `400 Bad Request` response with error
|
||||
details
|
||||
|
||||
#### Account management {id="oauth-20-account-management"}
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
All account management is done via the homeserver's web UI.
|
||||
|
||||
This specification defines extensions to the [OAuth Authorization Server
|
||||
Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
|
||||
to offer clients a way to deep-link to the account management capabilities of
|
||||
the homeserver to allow the user to complete the account management operations
|
||||
in a browser.
|
||||
|
||||
##### Account management URL discovery
|
||||
|
||||
The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
|
||||
extended to include the following **optional** fields.
|
||||
|
||||
{{% definition path="schemas/oauth2-account-management-server-metadata" %}}
|
||||
|
||||
##### Account management URL parameters
|
||||
|
||||
The account management URL MAY accept the following minimum query parameters.
|
||||
|
||||
{{% definition path="schemas/oauth2-account-management-url" %}}
|
||||
|
||||
##### Account management URL actions
|
||||
|
||||
Account management actions are unique to the application. They SHOULD follow the
|
||||
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar)
|
||||
where feasible. The Matrix-specific actions are:
|
||||
|
||||
| Action | Description |
|
||||
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `org.matrix.profile` | The user wishes to view/edit their profile (name, avatar, contact details). |
|
||||
| `org.matrix.devices_list` | The user wishes to view a list of their devices. |
|
||||
| `org.matrix.device_view` | The user wishes to view the details of a specific device. A `device_id` SHOULD be provided. |
|
||||
| `org.matrix.device_delete` | The user wishes to delete/log out a specific device. A `device_id` SHOULD be provided. |
|
||||
| `org.matrix.account_deactivate` | The user wishes to deactivate their account. |
|
||||
| `org.matrix.cross_signing_reset` | The user wishes to reset their cross-signing identity. Servers SHOULD use this action in the URL of the [`m.oauth`](#oauth-authentication) UIA type. |
|
||||
|
||||
### Account moderation
|
||||
|
||||
#### Account locking
|
||||
|
|
|
|||
|
|
@ -35,14 +35,6 @@ 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: []
|
||||
|
|
|
|||
|
|
@ -86,13 +86,5 @@ 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']
|
||||
|
|
|
|||
|
|
@ -170,13 +170,6 @@ 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: []
|
||||
|
|
@ -239,13 +232,6 @@ 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: []
|
||||
|
|
|
|||
|
|
@ -139,32 +139,6 @@ paths:
|
|||
items:
|
||||
type: string
|
||||
description: A prompt value that the server supports.
|
||||
account_management_uri:
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
The URL where the user is able to access the account management capabilities
|
||||
of the homeserver.
|
||||
|
||||
This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
|
||||
account_management_actions_supported:
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
type: array
|
||||
description: |-
|
||||
List of actions that the account management URL supports.
|
||||
|
||||
This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
|
||||
items:
|
||||
type: string
|
||||
enum:
|
||||
- "org.matrix.profile"
|
||||
- "org.matrix.devices_list"
|
||||
- "org.matrix.device_view"
|
||||
- "org.matrix.device_delete"
|
||||
- "org.matrix.account_deactivate"
|
||||
- "org.matrix.cross_signing_reset"
|
||||
description: An action that the account management URL supports.
|
||||
required:
|
||||
- issuer
|
||||
- authorization_endpoint
|
||||
|
|
@ -185,15 +159,6 @@ paths:
|
|||
"grant_types_supported": ["authorization_code", "refresh_token"],
|
||||
"response_modes_supported": ["query", "fragment"],
|
||||
"code_challenge_methods_supported": ["S256"],
|
||||
"account_management_uri": "https://account.example.com/manage",
|
||||
"account_management_actions_supported": [
|
||||
"org.matrix.profile",
|
||||
"org.matrix.devices_list",
|
||||
"org.matrix.device_view",
|
||||
"org.matrix.device_delete",
|
||||
"org.matrix.account_deactivate",
|
||||
"org.matrix.cross_signing_reset",
|
||||
],
|
||||
}
|
||||
tags:
|
||||
- Session management
|
||||
|
|
|
|||
|
|
@ -72,15 +72,6 @@ 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
|
||||
|
|
|
|||
|
|
@ -37,22 +37,6 @@ 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.
|
||||
|
|
@ -91,22 +75,6 @@ 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.
|
||||
|
|
|
|||
|
|
@ -1,30 +0,0 @@
|
|||
# Copyright 2026 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: OAuth 2.0 Server Metadata Account Management Extension
|
||||
properties:
|
||||
account_management_uri:
|
||||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
The URL where the user is able to access the account management capabilities of the
|
||||
server.
|
||||
account_management_actions_supported:
|
||||
type: array
|
||||
description: |-
|
||||
List of [actions](/client-server-api/#account-management-url-actions) that the account
|
||||
management URL supports.
|
||||
items:
|
||||
type: string
|
||||
description: An action that the account management URL supports.
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
# Copyright 2026 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: OAuth 2.0 Account Management URL Query Parameters
|
||||
properties:
|
||||
action:
|
||||
type: string
|
||||
description: |-
|
||||
The action that the user wishes to take. Must match one of the actions advertised by the
|
||||
server in [`account_management_actions_supported`](/client-server-api/#account-management-url-discovery).
|
||||
device_id:
|
||||
type: string
|
||||
description: |-
|
||||
For Matrix-specific actions, the user's device ID. Actions which don't support the device ID
|
||||
will ignore it.
|
||||
|
||||
If the `org.matrix.device_view` or `org.matrix.device_delete` actions are advertised as
|
||||
supported by the server then the server SHOULD support the `device_id` parameter.
|
||||
Loading…
Reference in a new issue