mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-28 21:34:09 +02:00
Compare commits
9 commits
1b2b150c0e
...
68f02a6e4c
| Author | SHA1 | Date | |
|---|---|---|---|
|
68f02a6e4c | ||
|
|
6e7c8a6da0 | ||
|
|
edea11e610 | ||
|
|
c8ae75a342 | ||
|
|
70c7d59caa | ||
|
|
70d2005743 | ||
|
|
293012d12f | ||
|
|
80c6ffd1d8 | ||
|
|
8350b88a3d |
1
changelogs/client_server/newsfragments/2270.feature
Normal file
1
changelogs/client_server/newsfragments/2270.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
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
changelogs/internal/newsfragments/2222.clarification
Normal file
1
changelogs/internal/newsfragments/2222.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Clarify vendor prefixing requirements.
|
||||
|
|
@ -645,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.
|
||||
UI that can be accessed by users via the [account management URL](#oauth-20-account-management).
|
||||
|
||||
### Legacy API
|
||||
|
||||
|
|
@ -2271,6 +2271,54 @@ 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 fields:
|
||||
|
||||
| Field | Description |
|
||||
|----------------------------------------|-------------------------------------------------------------------------------------------------|
|
||||
| `account_management_uri` | The URL where the user is able to access the account management capabilities of the homeserver. |
|
||||
| `account_management_actions_supported` | An array of actions that the account management URL supports, as defined below. |
|
||||
|
||||
##### Account management URL parameters
|
||||
|
||||
The account management URL MAY accept the following query parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|-------------|---------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `action` | **Optional**. The action that the user wishes to take. Must match one of the actions in `account_management_actions_supported` above. |
|
||||
| `device_id` | **Optional**. Identifies a particular Matrix device ID for actions that support 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.
|
||||
|
||||
##### Account management URL actions
|
||||
|
||||
The following account management actions are defined:
|
||||
|
||||
| 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
|
||||
|
|
|
|||
|
|
@ -408,41 +408,9 @@ development or testing data.
|
|||
that a particular MSC works) do not have to follow this process.
|
||||
|
||||
1. Have an idea for a feature.
|
||||
1. Implement the feature using unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags as appropriate.
|
||||
- When using unstable endpoints, they MUST include a vendor
|
||||
prefix. For example:
|
||||
`/_matrix/client/unstable/com.example/login`. Vendor prefixes
|
||||
throughout Matrix always use the Java package naming convention.
|
||||
The MSC for the feature should identify which preferred vendor
|
||||
prefix is to be used by early adopters.
|
||||
- Note that unstable namespaces do not automatically inherit
|
||||
endpoints from stable namespaces: for example, the fact that
|
||||
`/_matrix/client/r0/sync` exists does not imply that
|
||||
`/_matrix/client/unstable/com.example/sync` exists.
|
||||
- If the client needs to be sure the server supports the feature,
|
||||
an unstable feature flag that MUST be vendor prefixed is to be
|
||||
used. This kind of flag shows up in the `unstable_features`
|
||||
section of `/versions` as, for example, `com.example.new_login`.
|
||||
The MSC for the feature should identify which preferred feature
|
||||
flag is to be used by early adopters.
|
||||
- When using this approach correctly, the implementation can
|
||||
ship/release the feature at any time, so long as the
|
||||
implementation is able to accept the technical debt that results
|
||||
from needing to provide adequate backwards and forwards
|
||||
compatibility. The implementation MUST support the flag (and
|
||||
server-side implementation) disappearing and be generally safe
|
||||
for users. Note that implementations early in the MSC review
|
||||
process may also be required to provide backwards compatibility
|
||||
with earlier editions of the proposal.
|
||||
- If the implementation cannot support the technical debt (or if
|
||||
it's impossible to provide forwards/backwards compatibility -
|
||||
e.g. a user authentication change which can't be safely rolled
|
||||
back), the implementation should not attempt to implement the
|
||||
feature and should instead wait for a spec release.
|
||||
- If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change
|
||||
so that implementations can adapt as needed.
|
||||
1. Implement the feature using [unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
|
||||
as appropriate.
|
||||
1. In parallel, or ahead of implementation, open an MSC and solicit
|
||||
review per above.
|
||||
1. Before FCP can be called, the Spec Core Team will require evidence
|
||||
|
|
@ -452,10 +420,7 @@ that a particular MSC works) do not have to follow this process.
|
|||
forwards/backwards compatibility concerns mentioned here.
|
||||
1. The FCP process is completed, and assuming nothing is flagged the
|
||||
MSC lands.
|
||||
1. Implementations can now switch to using stable prefixes
|
||||
(for example, for an endpoint, moving from
|
||||
`/unstable/org.matrix.mscxxxx/frobnicate`
|
||||
to `/v1/frobnicate`), assuming that the change
|
||||
1. Implementations can now switch to using stable prefixes, assuming that the change
|
||||
is backwards compatible with older implementations. In the rare occasion
|
||||
where backwards compatibility is not possible without a new spec release,
|
||||
implementations should continue to use unstable prefixes.
|
||||
|
|
@ -471,13 +436,6 @@ that a particular MSC works) do not have to follow this process.
|
|||
started supporting the new spec release, some noise should be raised
|
||||
in the general direction of the implementation.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
|
||||
com.example/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
In summary:
|
||||
|
||||
- Implementations MUST NOT use stable endpoints before the MSC has
|
||||
|
|
@ -489,14 +447,90 @@ In summary:
|
|||
- Implementations SHOULD be wary of the technical debt they are
|
||||
incurring by moving faster than the spec.
|
||||
- The vendor prefix is chosen by the developer of the feature, using
|
||||
the Java package naming convention. The foundation's preferred
|
||||
vendor prefix is `org.matrix`.
|
||||
the Java package naming convention.
|
||||
- The vendor prefixes, unstable feature flags, and unstable endpoints
|
||||
should be included in the MSC, though the MSC MUST be written in a
|
||||
way that proposes new stable endpoints. Typically this is solved by
|
||||
a small table at the bottom mapping the various values from stable
|
||||
to unstable.
|
||||
|
||||
#### Unstable endpoints, features and vendor prefixes
|
||||
|
||||
Unstable endpoints MUST use `/unstable` as the endpoint version and a
|
||||
vendor prefix in Java package naming format. For example:
|
||||
`/_matrix/client/unstable/com.example.mscxxxx/login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Proposal authors operating with a Matrix.org Foundation mandate SHOULD use
|
||||
a vendor prefix within the `org.matrix` namespace. This namespace is otherwise
|
||||
restricted. Authors who don't own a domain MAY use the `io.github` namespace
|
||||
instead.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that unstable namespaces do not automatically inherit endpoints from
|
||||
stable namespaces: for example, the fact that `/_matrix/client/v3/sync`
|
||||
exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync`
|
||||
exists.
|
||||
|
||||
Vendor prefixes MUST also be used for:
|
||||
|
||||
- New parameters on existing endpoints. For example:
|
||||
`/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`.
|
||||
- New properties in existing JSON objects. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
|
||||
"displayname": "Alice Margatroid",
|
||||
"com.example.mscxxxx.phone": [{
|
||||
"type": "landline",
|
||||
"number": "+1-206-555-7000"
|
||||
}],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- New values for existing parameters or properties. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL",
|
||||
"error": "The email address you provided is invalid."
|
||||
}
|
||||
```
|
||||
|
||||
If the client needs to be sure the server supports the feature, an
|
||||
unstable feature flag that MUST also be vendor prefixed is to be used.
|
||||
This flag shows up in the `unstable_features` section of
|
||||
[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
|
||||
as, for example, `com.example.mscxxxx.new_login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`,
|
||||
not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When using this approach correctly, the implementation can release
|
||||
the feature at any time, so long as the implementation is able to
|
||||
accept the technical debt that results from needing to provide
|
||||
adequate backwards and forwards compatibility. The implementation
|
||||
MUST support the flag (and server-side implementation) disappearing
|
||||
and be generally safe for users. Note that implementations early in
|
||||
the MSC review process may also be required to provide backwards
|
||||
compatibility with earlier editions of the proposal.
|
||||
|
||||
If the implementation cannot support the technical debt (or if it's
|
||||
impossible to provide forwards/backwards compatibility - e.g. a user
|
||||
authentication change which can't be safely rolled back), the
|
||||
implementation should not attempt to implement the feature and should
|
||||
instead wait for a spec release.
|
||||
|
||||
If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change so
|
||||
that implementations can adapt as needed.
|
||||
|
||||
### Placeholder MSCs
|
||||
|
||||
Some proposals may contain security-sensitive or private context which can't be
|
||||
|
|
|
|||
|
|
@ -139,6 +139,32 @@ 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
|
||||
|
|
@ -159,6 +185,15 @@ 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue