mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-03 17:54:14 +02:00
Merge e49e19f2e3 into 2192bfa996
This commit is contained in:
Richard van der Hoff
GitHub
commit
83c9a098b2
|
|
@ -100,7 +100,7 @@ this.
|
|||
|
||||
### Homeserver -> Application Service API
|
||||
|
||||
#### Authorization
|
||||
#### Authorisation
|
||||
|
||||
{{% changed-in v="1.4" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ No significant changes.
|
|||
|
||||
**Spec Clarifications**
|
||||
|
||||
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- For room versions 6 and 7, clarify in the authorisation rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
|
||||
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
|
||||
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
|
||||
|
|
|
|||
|
|
@ -108,12 +108,12 @@ No significant changes.
|
|||
|
||||
|
||||
- Improve readability and understanding of the state resolution algorithms. ([#1037](https://github.com/matrix-org/matrix-spec/issues/1037), [#1042](https://github.com/matrix-org/matrix-spec/issues/1042), [#1043](https://github.com/matrix-org/matrix-spec/issues/1043), [#1120](https://github.com/matrix-org/matrix-spec/issues/1120))
|
||||
- Improve readability of the authorization rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- Improve readability of the authorisation rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event. ([#1093](https://github.com/matrix-org/matrix-spec/issues/1093))
|
||||
- Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667). ([#1099](https://github.com/matrix-org/matrix-spec/issues/1099))
|
||||
- For all room versions: Add `m.federate` to the authorization rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For all room versions: Add `m.federate` to the authorisation rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events. ([#1107](https://github.com/matrix-org/matrix-spec/issues/1107))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorisation rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ date: 2022-09-29
|
|||
<strong>Breaking Changes</strong>
|
||||
|
||||
|
||||
- Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
- Replace homeserver authorisation approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
|
|
|||
|
|
@ -263,7 +263,7 @@ matching the threepid was found.
|
|||
: The request or entity was too large.
|
||||
|
||||
`M_UNAUTHORIZED`
|
||||
: The request was not correctly authorized. Usually due to login failures.
|
||||
: The request was not correctly authorised. Usually due to login failures.
|
||||
|
||||
`M_UNSUPPORTED_ROOM_VERSION`
|
||||
: The client's request to create a room used a room version that the
|
||||
|
|
@ -543,7 +543,7 @@ With the legacy API, a client can register a new account with the
|
|||
With the OAuth 2.0 API, a client can't register a new account directly. The end
|
||||
user must do that directly in the homeserver's web UI. However, the client can
|
||||
signal to the homeserver that the user wishes to create a new account with the
|
||||
[`prompt=create`](#user-registration) parameter during authorization.
|
||||
[`prompt=create`](#user-registration) parameter during authorisation.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
|
|
@ -559,7 +559,7 @@ endpoint. To invalidate the access token the client must call the [`/logout`](#p
|
|||
endpoint.
|
||||
|
||||
With the OAuth 2.0 API, a client can obtain an access token by using one of the
|
||||
[grant types](#grant-types) supported by the homeserver and authorizing the
|
||||
[grant types](#grant-types) supported by the homeserver and authorising the
|
||||
proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
|
||||
invalidate the access token the client must use [token revocation](#token-revocation).
|
||||
|
||||
|
|
@ -1736,7 +1736,7 @@ or best practice recommendations.
|
|||
|
||||
The main change for end users with this API is that all the account management
|
||||
occurs in their browser on the homeserver's web UI. This is where they will
|
||||
register a new account or log into an existing account and authorize a client to
|
||||
register a new account or log into an existing account and authorise a client to
|
||||
access their Matrix account. This means that the homeserver has complete control
|
||||
over the requirements to create a new account and is not limited by the steps
|
||||
defined in this specification. It also means that less trust is given to clients
|
||||
|
|
@ -1757,27 +1757,27 @@ authentication type.
|
|||
|
||||
1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
|
||||
2. [Register the client with the homeserver](#client-registration).
|
||||
3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
|
||||
the client with the [authorization code grant](#authorization-code-grant) or
|
||||
[device authorization grant](#device-authorization-grant).
|
||||
3. [Obtain an access token](#login-flows) by authorising a [scope](#scope) for
|
||||
the client with the [authorisation code grant](#authorisation-code-grant) or
|
||||
[device authorisation grant](#device-authorisation-grant).
|
||||
4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
|
||||
5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
|
||||
|
||||
#### Login flows
|
||||
|
||||
Logging in and obtaining an access token with the OAuth 2.0 API should be done
|
||||
using either the [authorization code grant](#authorization-code-grant) or
|
||||
[device authorization grant](#device-authorization-grant). In the context of the
|
||||
using either the [authorisation code grant](#authorisation-code-grant) or
|
||||
[device authorisation grant](#device-authorisation-grant). In the context of the
|
||||
Matrix specification, this means requesting a [scope](#scope) including full
|
||||
client-server API read/write access and allocating a device ID.
|
||||
|
||||
##### Authorization code flow
|
||||
##### Authorisation code flow
|
||||
|
||||
This login flow uses the [authorization code grant](#authorization-code-grant)
|
||||
This login flow uses the [authorisation code grant](#authorisation-code-grant)
|
||||
and is suitable for clients where the following criteria are met:
|
||||
|
||||
- There is a web browser available for the user to complete authentication and
|
||||
authorization.
|
||||
authorisation.
|
||||
- The client can receive the callback via a redirect from the web browser.
|
||||
|
||||
Once the client has retrieved the [server metadata](#server-metadata-discovery)
|
||||
|
|
@ -1786,20 +1786,20 @@ the client needs to generate the following values:
|
|||
- `device_id`: a unique identifier for this device; see the
|
||||
[`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
|
||||
- `state`: a unique opaque identifier, like a [transaction ID](#transaction-identifiers),
|
||||
that will allow the client to maintain state between the authorization request
|
||||
that will allow the client to maintain state between the authorisation request
|
||||
and the callback.
|
||||
- `code_verifier`: a cryptographically random value that will allow to make sure
|
||||
that the client that makes the token request for a given `code` is the same
|
||||
one that made the authorization request.
|
||||
one that made the authorisation request.
|
||||
|
||||
It is defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) as
|
||||
a high-entropy cryptographic random string using the characters `[A-Z]`,
|
||||
`[a-z]`, `[0-9]`, `-`, `.`, `_` and `~` with a minimum length of 43 characters
|
||||
and a maximum length of 128 characters.
|
||||
|
||||
**Authorization request**
|
||||
**Authorisation request**
|
||||
|
||||
The client then constructs the authorization request URL using the
|
||||
The client then constructs the authorisation request URL using the
|
||||
`authorization_endpoint` value, with the following query parameters:
|
||||
|
||||
| Parameter | Value |
|
||||
|
|
@ -1813,7 +1813,7 @@ The client then constructs the authorization request URL using the
|
|||
| `code_challenge` | Computed from the `code_verifier` value generated previously using the SHA-256 algorithm, as described in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636). |
|
||||
| `code_challenge_method` | `S256` |
|
||||
|
||||
This authorization request URL must be opened in the user's browser:
|
||||
This authorisation request URL must be opened in the user's browser:
|
||||
|
||||
- For web-based clients, this can be done through a redirection or by opening
|
||||
the URL in a new tab.
|
||||
|
|
@ -1822,7 +1822,7 @@ This authorization request URL must be opened in the user's browser:
|
|||
[`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
|
||||
on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
|
||||
|
||||
Sample authorization request, with extra whitespaces for readability:
|
||||
Sample authorisation request, with extra whitespaces for readability:
|
||||
|
||||
```nohighlight
|
||||
https://account.example.com/oauth2/auth?
|
||||
|
|
@ -1839,7 +1839,7 @@ https://account.example.com/oauth2/auth?
|
|||
<a id="callback"></a> **Callback**
|
||||
|
||||
Once completed, the user is redirected to the `redirect_uri`, with either a
|
||||
successful or failed authorization in the URL fragment or query parameters.
|
||||
successful or failed authorisation in the URL fragment or query parameters.
|
||||
Whether the parameters are in the URL fragment or query parameters is determined
|
||||
by the `response_mode` value:
|
||||
|
||||
|
|
@ -1853,15 +1853,15 @@ clients SHOULD use the `fragment` response mode if the `redirect_uri` is an
|
|||
HTTPS URI with a remote host.
|
||||
|
||||
In both success and failure cases, the parameters will include the `state` value
|
||||
used in the authorization request.
|
||||
used in the authorisation request.
|
||||
|
||||
A successful authorization will have a `code` value, for example:
|
||||
A successful authorisation will have a `code` value, for example:
|
||||
|
||||
```nohighlight
|
||||
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
|
||||
```
|
||||
|
||||
A failed authorization will have the following values:
|
||||
A failed authorisation will have the following values:
|
||||
|
||||
- `error`: the error code
|
||||
- `error_description`: the error description (optional)
|
||||
|
|
@ -1875,7 +1875,7 @@ https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&e
|
|||
|
||||
**Token request**
|
||||
|
||||
The client then exchanges the authorization code to obtain an access token using
|
||||
The client then exchanges the authorisation code to obtain an access token using
|
||||
the token endpoint.
|
||||
|
||||
This is done by making a POST request to the `token_endpoint` with the following
|
||||
|
|
@ -1885,9 +1885,9 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
|||
|-----------------|------------------------------------------------------------|
|
||||
| `grant_type` | `authorization_code` |
|
||||
| `code` | The value of `code` obtained from the callback. |
|
||||
| `redirect_uri` | The same `redirect_uri` used in the authorization request. |
|
||||
| `redirect_uri` | The same `redirect_uri` used in the authorisation request. |
|
||||
| `client_id` | The client ID returned from client registration. |
|
||||
| `code_verifier` | The value generated at the start of the authorization flow. |
|
||||
| `code_verifier` | The value generated at the start of the authorisation flow. |
|
||||
|
||||
The server replies with a JSON object containing the access token, the token
|
||||
type, the expiration time, and the refresh token.
|
||||
|
|
@ -1922,13 +1922,13 @@ Sample response:
|
|||
Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
|
||||
endpoint to get the user ID that owns the access token.
|
||||
|
||||
##### Device authorization flow
|
||||
##### Device authorisation flow
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
This flow uses the [device authorization grant](#device-authorization-grant) to
|
||||
This flow uses the [device authorisation grant](#device-authorisation-grant) to
|
||||
allow clients to obtain an access token without needing to directly interact
|
||||
with a web browser. Instead, the user completes authorization on a web browser
|
||||
with a web browser. Instead, the user completes authorisation on a web browser
|
||||
that can be a separate device.
|
||||
|
||||
This is useful for devices with limited input
|
||||
|
|
@ -1941,7 +1941,7 @@ the client needs to generate following value:
|
|||
- `device_id`: a unique identifier for this device; see the
|
||||
[`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
|
||||
|
||||
**Device authorization request**
|
||||
**Device authorisation request**
|
||||
|
||||
The client sends a `application/x-www-form-urlencoded` encoded `POST` request to
|
||||
the `device_authorization_endpoint` as defined in
|
||||
|
|
@ -1952,7 +1952,7 @@ the `device_authorization_endpoint` as defined in
|
|||
| `client_id` | The client ID returned from client registration. |
|
||||
| `scope` | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
|
||||
|
||||
Sample device authorization request:
|
||||
Sample device authorisation request:
|
||||
|
||||
```
|
||||
POST /oauth2/device HTTP/1.1
|
||||
|
|
@ -1962,7 +1962,7 @@ Content-Type: application/x-www-form-urlencoded
|
|||
client_id=s6BhdRkqt3&scope=urn%3Amatrix%3Aclient%3Aapi%3A%2A%20urn%3Amatrix%3Aclient%3Adevice%3AAABBBCCCDDD
|
||||
```
|
||||
|
||||
**Device authorization response**
|
||||
**Device authorisation response**
|
||||
|
||||
The server responds with a JSON object as defined in
|
||||
[RFC 8628 section 3.2](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2),
|
||||
|
|
@ -1972,7 +1972,7 @@ containing:
|
|||
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `device_code` | The device verification code. |
|
||||
| `user_code` | An end-user verification code. |
|
||||
| `verification_uri` | The end-user verification URI on the authorization server. |
|
||||
| `verification_uri` | The end-user verification URI on the authorisation server. |
|
||||
| `verification_uri_complete` | Optionally, the URI which doesn't require the user to manually type the `user_code`, designed for non-textual transmission. |
|
||||
| `expires_in` | The lifetime in seconds of the `device_code` and `user_code`. |
|
||||
| `interval` | The minimum number of seconds the client should wait between polling requests to the token endpoint. If omitted, clients should default to 5. |
|
||||
|
|
@ -2009,13 +2009,13 @@ specific device characteristics and use case. For example:
|
|||
`verification_uri`) in the system browser.
|
||||
|
||||
The user opens the verification URI in a web browser, which may be on another
|
||||
device, and completes authentication and authorization.
|
||||
device, and completes authentication and authorisation.
|
||||
|
||||
**Token polling**
|
||||
|
||||
While the user is completing authorization, the client polls the
|
||||
While the user is completing authorisation, the client polls the
|
||||
`token_endpoint` for the outcome, at intervals no shorter than the `interval`
|
||||
value from the device authorization response.
|
||||
value from the device authorisation response.
|
||||
|
||||
The poll request is a `POST` to the `token_endpoint` with the following
|
||||
parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
||||
|
|
@ -2023,7 +2023,7 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
|||
| Parameter | Value |
|
||||
|---------------|----------------------------------------------------------------|
|
||||
| `grant_type` | `urn:ietf:params:oauth:grant-type:device_code` |
|
||||
| `device_code` | The `device_code` from the device authorization response. |
|
||||
| `device_code` | The `device_code` from the device authorisation response. |
|
||||
| `client_id` | The client ID returned from client registration. |
|
||||
|
||||
Sample token polling request:
|
||||
|
|
@ -2039,11 +2039,11 @@ grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=Gm
|
|||
The server responds as defined in [RFC 8628 section
|
||||
3.5](https://datatracker.ietf.org/doc/html/rfc8628#section-3.5):
|
||||
|
||||
- While authorization is pending, the server returns an `authorization_pending`
|
||||
- While authorisation is pending, the server returns an `authorization_pending`
|
||||
error (or `slow_down` if the client is polling too frequently).
|
||||
- If authorization is denied, the server returns an `access_denied` error.
|
||||
- If authorisation is denied, the server returns an `access_denied` error.
|
||||
- If the device code expires, the server returns an `expired_token` error.
|
||||
- On successful authorization, the server returns a JSON object containing the
|
||||
- On successful authorisation, the server returns a JSON object containing the
|
||||
access token, token type, expiration time, refresh token, and scope:
|
||||
|
||||
```json
|
||||
|
|
@ -2075,7 +2075,7 @@ request to the `token_endpoint` with the following parameters, encoded as
|
|||
| `client_id` | The client ID returned from client registration. |
|
||||
|
||||
The server replies with a JSON object containing the new access token, the token
|
||||
type, the expiration time, and a new refresh token, like in the authorization
|
||||
type, the expiration time, and a new refresh token, like in the authorisation
|
||||
flow.
|
||||
|
||||
#### Server metadata discovery
|
||||
|
|
@ -2084,7 +2084,7 @@ flow.
|
|||
|
||||
#### Client registration
|
||||
|
||||
Before being able to use the authorization flow to obtain an access token, a
|
||||
Before being able to use the authorisation flow to obtain an access token, a
|
||||
client needs to obtain a `client_id` by registering itself with the server.
|
||||
|
||||
This should be done via OAuth 2.0 Dynamic Client Registration as defined in
|
||||
|
|
@ -2092,7 +2092,7 @@ This should be done via OAuth 2.0 Dynamic Client Registration as defined in
|
|||
|
||||
##### Client metadata
|
||||
|
||||
In OAuth 2.0, clients register a set of metadata values with the authorization
|
||||
In OAuth 2.0, clients register a set of metadata values with the authorisation
|
||||
server, which associates it with a newly generated `client_id`. These values are
|
||||
used to describe the client to the user and define how the client interacts with
|
||||
the server.
|
||||
|
|
@ -2172,7 +2172,7 @@ With the same client URI, the following are invalid redirect URIs:
|
|||
- The scheme MUST be `http`.
|
||||
- The host part MUST be `localhost`, `127.0.0.1`, or `[::1]`.
|
||||
- There MUST NOT be a port. The homeserver MUST then accept any port number
|
||||
during the authorization flow.
|
||||
during the authorisation flow.
|
||||
3. **Claimed `https` Scheme URI**
|
||||
|
||||
Some operating systems allow apps to claim `https` scheme URIs in the
|
||||
|
|
@ -2271,7 +2271,7 @@ choose to delete client registrations that don't have an active session. The
|
|||
server MUST NOT delete client registrations that have an active session.
|
||||
|
||||
Clients MUST perform a new client registration at the start of each
|
||||
authorization flow.
|
||||
authorisation flow.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Because each client on each user device will do its own registration, they may
|
||||
|
|
@ -2287,7 +2287,7 @@ registrations.
|
|||
|
||||
#### Scope
|
||||
|
||||
The client requests a scope in the OAuth 2.0 authorization flow, which is then
|
||||
The client requests a scope in the OAuth 2.0 authorisation flow, which is then
|
||||
associated to the generated access and refresh tokens. This provides a framework
|
||||
for obtaining user consent.
|
||||
|
||||
|
|
@ -2380,7 +2380,7 @@ This definition matches:
|
|||
[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) and other RFCs define
|
||||
several "grant types": ways to obtain an ["access token"](#using-access-tokens).
|
||||
|
||||
All these grants types require the client to know the following [authorization
|
||||
All these grants types require the client to know the following [authorisation
|
||||
server metadata](#server-metadata-discovery):
|
||||
- `token_endpoint`
|
||||
- `grant_types_supported`
|
||||
|
|
@ -2388,17 +2388,17 @@ server metadata](#server-metadata-discovery):
|
|||
The client must also have obtained a `client_id` by [registering with the server](#client-registration).
|
||||
|
||||
This specification supports the following grant types:
|
||||
- [Authorization code grant](#authorization-code-grant)
|
||||
- {{% added-in v="1.18" %}} [Device authorization grant](#device-authorization-grant)
|
||||
- [Authorisation code grant](#authorisation-code-grant)
|
||||
- {{% added-in v="1.18" %}} [Device authorisation grant](#device-authorisation-grant)
|
||||
- [Refresh token grant](#refresh-token-grant)
|
||||
|
||||
##### Authorization code grant
|
||||
##### Authorisation code grant
|
||||
|
||||
As per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1),
|
||||
the authorization code grant lets the client obtain an access token through a
|
||||
the authorisation code grant lets the client obtain an access token through a
|
||||
browser redirect.
|
||||
|
||||
This grant requires the client to know the following [authorization server
|
||||
This grant requires the client to know the following [authorisation server
|
||||
metadata](#server-metadata-discovery):
|
||||
- `authorization_endpoint`
|
||||
- `response_types_supported`
|
||||
|
|
@ -2406,7 +2406,7 @@ metadata](#server-metadata-discovery):
|
|||
|
||||
To use this grant, homeservers and clients MUST:
|
||||
|
||||
- Support the authorization code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
|
||||
- Support the authorisation code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
|
||||
- Support the [refresh token grant](#refresh-token-grant).
|
||||
- Support PKCE using the `S256` code challenge method as per [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636).
|
||||
- Use [pre-registered](#client-registration), strict redirect URIs.
|
||||
|
|
@ -2414,34 +2414,34 @@ To use this grant, homeservers and clients MUST:
|
|||
Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
|
||||
for clients with an HTTPS redirect URI.
|
||||
|
||||
##### Device authorization grant
|
||||
##### Device authorisation grant
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
As per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), the device
|
||||
authorization grant lets clients on devices with limited input capabilities
|
||||
obtain an access token by having the user complete authorization on a separate
|
||||
authorisation grant lets clients on devices with limited input capabilities
|
||||
obtain an access token by having the user complete authorisation on a separate
|
||||
device with a web browser.
|
||||
|
||||
This grant requires the client to know the following [authorization server
|
||||
This grant requires the client to know the following [authorisation server
|
||||
metadata](#server-metadata-discovery):
|
||||
|
||||
- `device_authorization_endpoint`
|
||||
- `device_authorisation_endpoint`
|
||||
|
||||
To use this grant, homeservers and clients MUST:
|
||||
|
||||
- Support the device authorization grant as per
|
||||
- Support the device authorisation grant as per
|
||||
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628).
|
||||
- Support the [refresh token grant](#refresh-token-grant).
|
||||
|
||||
As with the [authorization code grant](#authorization-code-grant), when
|
||||
authorization is granted to a client, the homeserver MUST issue a refresh token
|
||||
As with the [authorisation code grant](#authorisation-code-grant), when
|
||||
authorisation is granted to a client, the homeserver MUST issue a refresh token
|
||||
to the client in addition to the access token. The access token and refresh
|
||||
token have the same lifetime constraints as described in the [refresh token
|
||||
grant](#refresh-token-grant) section.
|
||||
|
||||
The full flow for using this grant is described in the
|
||||
[device authorization flow](#device-authorization-flow).
|
||||
[device authorisation flow](#device-authorisation-flow).
|
||||
|
||||
##### Refresh token grant
|
||||
|
||||
|
|
@ -2449,7 +2449,7 @@ As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#sectio
|
|||
the refresh token grant lets the client exchange a refresh token for an access
|
||||
token.
|
||||
|
||||
When authorization is granted to a client, the homeserver MUST issue a refresh
|
||||
When authorisation is granted to a client, the homeserver MUST issue a refresh
|
||||
token to the client in addition to the access token.
|
||||
|
||||
The access token MUST be short-lived and SHOULD be refreshed using the
|
||||
|
|
@ -2476,7 +2476,7 @@ When a user wants to log out from a client, the client SHOULD use OAuth 2.0
|
|||
token revocation as defined in [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009).
|
||||
|
||||
The client makes a `POST` request to the `revocation_endpoint` that can be found
|
||||
in the [authorization server metadata](#server-metadata-discovery).
|
||||
in the [authorisation server metadata](#server-metadata-discovery).
|
||||
|
||||
The body of the request includes the following parameters, encoded as
|
||||
`application/x-www-form-urlencoded`:
|
||||
|
|
@ -2543,7 +2543,7 @@ The server SHOULD return one of the following responses:
|
|||
|
||||
- If the token is already revoked or invalid, the server returns a `200 OK`
|
||||
response
|
||||
- If the client is not authorized to revoke the token, the server returns a
|
||||
- If the client is not authorised to revoke the token, the server returns a
|
||||
`401 Unauthorized` response
|
||||
- For other errors, the server returns a `400 Bad Request` response with error
|
||||
details
|
||||
|
|
@ -2551,18 +2551,18 @@ The server SHOULD return one of the following responses:
|
|||
#### User registration
|
||||
|
||||
Clients can signal to the server that the user desires to register a new account
|
||||
by initiating the [authorization code grant](#authorization-code-grant) with the `prompt=create` parameter
|
||||
set in the authorization request as defined in [Initiating User Registration via
|
||||
by initiating the [authorisation code grant](#authorisation-code-grant) with the `prompt=create` parameter
|
||||
set in the authorisation request as defined in [Initiating User Registration via
|
||||
OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
|
||||
|
||||
Whether the homeserver supports this parameter is advertised by the
|
||||
`prompt_values_supported` authorization server metadata.
|
||||
`prompt_values_supported` authorisation server metadata.
|
||||
|
||||
Servers that support this parameter SHOULD show the account registration UI in
|
||||
the browser.
|
||||
|
||||
The `prompt=create` parameter is not supported when using the [device
|
||||
authorization grant](#device-authorization-grant).
|
||||
authorisation grant](#device-authorisation-grant).
|
||||
|
||||
#### Account management {id="oauth-20-account-management"}
|
||||
|
||||
|
|
@ -2570,7 +2570,7 @@ authorization grant](#device-authorization-grant).
|
|||
|
||||
All account management is done via the homeserver's web UI.
|
||||
|
||||
This specification defines extensions to the [OAuth Authorization Server
|
||||
This specification defines extensions to the [OAuth Authorisation 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
|
||||
|
|
@ -2578,7 +2578,7 @@ in a browser.
|
|||
|
||||
##### Account management URL discovery
|
||||
|
||||
The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
|
||||
The [OAuth 2.0 authorisation server metadata](#server-metadata-discovery) is
|
||||
extended to include the following **optional** fields.
|
||||
|
||||
{{% definition path="schemas/oauth2-account-management-server-metadata" %}}
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ The available room versions are:
|
|||
- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
|
||||
signing key validity periods.
|
||||
- [Version 6](/rooms/v6) - **Stable**. Alters several
|
||||
authorization rules for events.
|
||||
authorisation rules for events.
|
||||
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
|
||||
- [Version 8](/rooms/v8) - **Stable**. Adds a join rule to allow members
|
||||
of another room to join without invite.
|
||||
|
|
@ -85,7 +85,7 @@ The available room versions are:
|
|||
|
||||
Room versions are used to change properties of rooms that may not be
|
||||
compatible with other servers. For example, changing the rules for event
|
||||
authorization would cause older servers to potentially end up in a
|
||||
authorisation would cause older servers to potentially end up in a
|
||||
split-brain situation due to not understanding the new rules.
|
||||
|
||||
A room version is defined as a string of characters which MUST NOT
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -123,11 +123,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorization rules is not present in the state, then
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ in the same respect, so does not need a signature from that server.
|
|||
The event must still be signed by the server denoted by the `sender` property,
|
||||
however.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
---
|
||||
{{% added-in v=3 %}} In room versions 1 and 2, redactions were
|
||||
explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
|
||||
explicitly part of the [authorisation rules](/rooms/v1/#authorisation-rules)
|
||||
under Rule 11. As of room version 3, these conditions no longer exist as
|
||||
represented by [this version's authorization rules](#authorization-rules).
|
||||
represented by [this version's authorisation rules](#authorisation-rules).
|
||||
|
||||
While redactions are always accepted by the authorization rules for
|
||||
While redactions are always accepted by the authorisation rules for
|
||||
events, they should not be sent to clients until both the redaction
|
||||
event and the event the redaction affects have been received, and can
|
||||
be validated. If both events are valid and have been seen by the server,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ Events in version 1 rooms have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ results of the resolution so far.
|
|||
`sha1(event_id)`.
|
||||
- Add the first event in the list to *R*.
|
||||
- For each subsequent event in the list, check that the event
|
||||
would be allowed by the authorization rules for a room in state
|
||||
would be allowed by the authorisation rules for a room in state
|
||||
*R*. If the event would be allowed, then update *R* with the
|
||||
event and continue with the next event in the list. If it would
|
||||
not be allowed, stop and continue below with `m.room.join_rules`
|
||||
|
|
@ -115,7 +115,7 @@ results of the resolution so far.
|
|||
events.
|
||||
- Repeat the above process for conflicts between `m.room.member`
|
||||
events.
|
||||
- No other events affect the authorization rules, so for all other
|
||||
- No other events affect the authorisation rules, so for all other
|
||||
conflicts, just pick the event with the highest depth and lowest
|
||||
`sha1(event_id)` that passes authentication in *R* and add it to
|
||||
*R*.
|
||||
|
|
|
|||
|
|
@ -71,13 +71,13 @@ power levels could be represented as strings for backwards compatibility.
|
|||
|
||||
This backwards compatibility is removed in this room version - power levels MUST NOT
|
||||
be represented as strings within this room version. Power levels which are not
|
||||
correctly structured are rejected under the authorization rules below.
|
||||
correctly structured are rejected under the authorisation rules below.
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -80,11 +80,11 @@ For improved compatibility with newer clients, servers should add a `redacts` pr
|
|||
to the `content` of `m.room.redaction` events in *older* room versions when serving
|
||||
such events over the Client-Server API.
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -43,11 +43,11 @@ Room version 12 is based upon room version 11 with the following considerations.
|
|||
|
||||
{{% rver-fragment name="v12-event-format" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -267,7 +267,7 @@ algorithm found in [room version 2](/rooms/v2) with the following modifications:
|
|||
now starts with an *empty* state map instead of the unconflicted state map.
|
||||
|
||||
2. A new [definition](#definitions) for *conflicted state subgraph* has been added
|
||||
which describes events that are required to authorize events during iterative
|
||||
which describes events that are required to authorise events during iterative
|
||||
auth checks.
|
||||
|
||||
3. To ensure the new conflicted state subgraph is actually referenced, the definition
|
||||
|
|
@ -405,11 +405,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorization rules is not present in the state, then
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ Events in rooms of this version have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -89,7 +89,7 @@ The complete structure of a event in a v3 room is shown below.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v=3 %}} `m.room.redaction` events are subject to auth rules in
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ the changes in this room version.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ version: 6
|
|||
---
|
||||
|
||||
This room version builds on [version 5](/rooms/v5) while changing various
|
||||
authorization rules performed on events.
|
||||
authorisation rules performed on events.
|
||||
|
||||
## Client considerations
|
||||
|
||||
|
|
@ -47,20 +47,20 @@ no longer be formatted as floats.
|
|||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% added-in v=6 %}} Rule 4, which related specifically to events
|
||||
of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
|
||||
authorization checks relating to state events.
|
||||
authorisation checks relating to state events.
|
||||
|
||||
{{% added-in v=6 %}} Additionally, the authorization rules for events of
|
||||
{{% added-in v=6 %}} Additionally, the authorisation rules for events of
|
||||
type `m.room.power_levels` now include a `notifications` property under
|
||||
`content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
|
||||
the `events` property.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -27,18 +27,18 @@ regarding client considerations is the resource that Client-Server API
|
|||
use cases should reference.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
Room version 7 adds new authorization rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorization rule changes,
|
||||
Room version 7 adds new authorisation rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorisation rule changes,
|
||||
as do the versions v6 is based upon.
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% added-in v=7 %}} For checks performed upon `m.room.member` events, a
|
||||
new point for `membership=knock` is added.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorization are:
|
||||
The types of state events that affect authorisation are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ Room version 8 adds a new join rule to allow members of a room to join another
|
|||
room without invite. Otherwise, the room version inherits all properties of
|
||||
[Room version 7](/rooms/v7).
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% added-in v=8 %}} For checks performed upon `m.room.member` events, new
|
||||
points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
### Authorization rules
|
||||
### Authorisation rules
|
||||
|
||||
{{% rver-fragment name="v8-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ description: |
|
|||
real-time, retrieve historic messages, and query profile or presence
|
||||
information about users on other servers. The APIs are implemented over HTTPS,
|
||||
with authentication provided by public key signatures both at the TLS
|
||||
transport layer and in HTTP Authorization headers.
|
||||
transport layer and in HTTP `Authorization` headers.
|
||||
|
||||
There are three main kinds of communication that occur between
|
||||
homeservers:
|
||||
|
|
@ -279,7 +279,7 @@ Every HTTP request made by a homeserver is authenticated using public
|
|||
key digital signatures. The request method, target and body are signed
|
||||
by wrapping them in a JSON object and signing it using the [JSON signing
|
||||
algorithm](/appendices#signing-json). The resulting signatures are added
|
||||
as an Authorization header with an auth scheme of `X-Matrix`. Note that
|
||||
as an `Authorization` header with an auth scheme of `X-Matrix`. Note that
|
||||
the target field should include the full path starting with `/_matrix/...`,
|
||||
including the `?` and any query parameters if present, but should not
|
||||
include the leading `https:`, nor the destination server's hostname.
|
||||
|
|
@ -307,7 +307,7 @@ section](#resolving-server-names) above do not affect these - the server
|
|||
names from before delegation would take place are used. This same
|
||||
condition applies throughout the request signing process.
|
||||
|
||||
Step 2 add Authorization header:
|
||||
Step 2 add `Authorization` header:
|
||||
|
||||
POST /target HTTP/1.1
|
||||
Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
|
||||
|
|
@ -346,9 +346,9 @@ def authorization_headers(origin_name, origin_signing_key,
|
|||
return ("Authorization", authorization_headers[0])
|
||||
```
|
||||
|
||||
The format of the Authorization header is given in
|
||||
The format of the `Authorization` header is given in
|
||||
[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In
|
||||
summary, the header begins with authorization scheme `X-Matrix`, followed by one
|
||||
summary, the header begins with authorisation scheme `X-Matrix`, followed by one
|
||||
or more spaces, followed by a comma-separated list of parameters written as
|
||||
name=value pairs. Zero or more spaces and tabs around each comma are allowed.
|
||||
The names are case insensitive and order does not matter. The
|
||||
|
|
@ -369,7 +369,7 @@ For compatibility with older servers, the sender should
|
|||
For compatibility with older servers, the recipient should allow colons to be
|
||||
included in values without requiring the value to be enclosed in quotes.
|
||||
|
||||
The authorization parameters to include are:
|
||||
The authorisation parameters to include are:
|
||||
|
||||
- `origin`: the server name of the sending server. This is the same as the
|
||||
`origin` field from JSON described in step 1.
|
||||
|
|
@ -378,8 +378,8 @@ The authorization parameters to include are:
|
|||
in step 1. For compatibility with older servers, recipients should accept
|
||||
requests without this parameter, but MUST always send it. If this property
|
||||
is included, but the value does not match the receiving server's name, the
|
||||
receiving server must deny the request with an HTTP status code 401
|
||||
Unauthorized.
|
||||
receiving server must deny the request with an HTTP status code `401
|
||||
Unauthorized`.
|
||||
- `key`: the ID, including the algorithm name, of the sending server's key used
|
||||
to sign the request.
|
||||
- `signature`: the signature of the JSON as calculated in step 1.
|
||||
|
|
@ -467,11 +467,11 @@ server must ensure that the event:
|
|||
2. Passes signature checks, otherwise it is dropped.
|
||||
3. Passes hash checks, otherwise it is redacted before being processed
|
||||
further.
|
||||
4. Passes authorization rules based on the event's auth events,
|
||||
4. Passes authorisation rules based on the event's auth events,
|
||||
otherwise it is rejected.
|
||||
5. Passes authorization rules based on the state before the event,
|
||||
5. Passes authorisation rules based on the state before the event,
|
||||
otherwise it is rejected.
|
||||
6. Passes authorization rules based on the current state of the room,
|
||||
6. Passes authorisation rules based on the current state of the room,
|
||||
otherwise it is "soft failed".
|
||||
7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
|
||||
by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
|
||||
|
|
@ -516,9 +516,9 @@ and must never populate the default power levels in a room as string values.
|
|||
See the [room version specification](/rooms) for more information.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
#### Authorization rules
|
||||
#### Authorisation rules
|
||||
|
||||
The rules governing whether an event is authorized depends on a set of
|
||||
The rules governing whether an event is authorised depends on a set of
|
||||
state. A given event is checked multiple times against different sets of
|
||||
state, as specified above. Each room version can have a different
|
||||
algorithm for how the rules work, and which rules are applied. For more
|
||||
|
|
@ -697,9 +697,9 @@ then any new event `D'` will not reference `C`:
|
|||
Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Retrieving event authorization information
|
||||
#### Retrieving event authorisation information
|
||||
|
||||
The homeserver may be missing event authorization information, or wish
|
||||
The homeserver may be missing event authorisation information, or wish
|
||||
to check with other servers to ensure it is receiving the correct auth
|
||||
chain. These APIs give the homeserver an avenue for getting the
|
||||
information it needs.
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -83,7 +83,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorized to modify this user's account
|
||||
The access token provided is not authorised to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -126,7 +126,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -151,7 +151,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -196,7 +196,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -253,7 +253,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorized to modify this user's account
|
||||
The access token provided is not authorised to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -296,7 +296,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -341,7 +341,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ paths:
|
|||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminSuspendUser
|
||||
security:
|
||||
|
|
@ -204,7 +204,7 @@ paths:
|
|||
is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminSuspendUser
|
||||
security:
|
||||
|
|
@ -309,7 +309,7 @@ paths:
|
|||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminLockUser
|
||||
security:
|
||||
|
|
@ -396,7 +396,7 @@ paths:
|
|||
is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminLockUser
|
||||
security:
|
||||
|
|
|
|||
|
|
@ -159,7 +159,7 @@ paths:
|
|||
"403":
|
||||
description: |-
|
||||
The public key of one of the keys is the same as one of the user\'s
|
||||
device IDs, or the request is not authorized for any other reason.
|
||||
device IDs, or the request is not authorised for any other reason.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ paths:
|
|||
name: userId
|
||||
required: true
|
||||
description: The id of the user uploading the filter. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
authorised to make requests for this user id.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ paths:
|
|||
summary: Authenticates the user.
|
||||
description: |-
|
||||
Authenticates the user, and issues an access token they can
|
||||
use to authorize themself in subsequent requests.
|
||||
use to authorise themself in subsequent requests.
|
||||
|
||||
If the client does not supply a `device_id`, the server must
|
||||
auto-generate one.
|
||||
|
|
@ -194,7 +194,7 @@ paths:
|
|||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorize other requests.
|
||||
This access token can then be used to authorise other requests.
|
||||
refresh_token:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ paths:
|
|||
summary: Invalidates a user access token
|
||||
description: |-
|
||||
Invalidates an existing access token, so that it can no longer be used for
|
||||
authorization. The device associated with the access token is also deleted.
|
||||
authorisation. The device associated with the access token is also deleted.
|
||||
[Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
|
||||
operationId: logout
|
||||
security:
|
||||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
summary: Invalidates all access tokens for a user
|
||||
description: |-
|
||||
Invalidates all access tokens for a user, so that they can no longer be used for
|
||||
authorization. This includes the access token that made this request. All devices
|
||||
authorisation. This includes the access token that made this request. All devices
|
||||
for the user are also deleted. [Device keys](/client-server-api/#device-keys) for the device are
|
||||
deleted alongside the device.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,22 +18,22 @@ info:
|
|||
paths:
|
||||
"/auth_metadata":
|
||||
get:
|
||||
summary: Get the OAuth 2.0 authorization server metadata.
|
||||
summary: Get the OAuth 2.0 authorisation server metadata.
|
||||
description: |-
|
||||
Gets the OAuth 2.0 authorization server metadata, as defined in
|
||||
Gets the OAuth 2.0 authorisation server metadata, as defined in
|
||||
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
|
||||
endpoint URLs and the supported parameters that can be used by the
|
||||
clients.
|
||||
|
||||
This endpoint definition includes only the fields that are meaningful in
|
||||
the context of the Matrix specification. The full list of possible
|
||||
fields is available in the [OAuth Authorization Server Metadata
|
||||
fields is available in the [OAuth Authorisation Server Metadata
|
||||
registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
|
||||
and normative definitions of them are available in their respective
|
||||
RFCs.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The authorization server metadata is relatively large and may change
|
||||
The authorisation server metadata is relatively large and may change
|
||||
over time. Clients should:
|
||||
|
||||
- Cache the metadata appropriately based on HTTP caching headers
|
||||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
operationId: getAuthMetadata
|
||||
responses:
|
||||
"200":
|
||||
description: The OAuth 2.0 authorization server metadata.
|
||||
description: The OAuth 2.0 authorisation server metadata.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -52,7 +52,7 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
The authorization server's issuer identifier, which is a URL that uses the
|
||||
The authorisation server's issuer identifier, which is a URL that uses the
|
||||
`https` scheme and has no query or fragment components.
|
||||
|
||||
This is not used in the context of the Matrix specification, but is required
|
||||
|
|
@ -61,7 +61,7 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the authorization endpoint, necessary to use the authorization code
|
||||
URL of the authorisation endpoint, necessary to use the authorisation code
|
||||
grant.
|
||||
token_endpoint:
|
||||
type: string
|
||||
|
|
@ -84,10 +84,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response type strings that the server supports at the
|
||||
authorization endpoint.
|
||||
authorisation endpoint.
|
||||
|
||||
This array MUST contain at least the `code` value, for clients to be able to
|
||||
use the authorization code grant.
|
||||
use the authorisation code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response type that the server supports.
|
||||
|
|
@ -98,12 +98,12 @@ paths:
|
|||
endpoint.
|
||||
|
||||
This array MUST contain at least the `authorization_code` and `refresh_token`
|
||||
values, for clients to be able to use the authorization code grant and refresh
|
||||
values, for clients to be able to use the authorisation code grant and refresh
|
||||
token grant, respectively.
|
||||
|
||||
{{% added-in v="1.18" %}} It MAY also contain
|
||||
`urn:ietf:params:oauth:grant-type:device_code` to indicate support for the
|
||||
[device authorization grant](/client-server-api/#device-authorization-grant).
|
||||
[device authorisation grant](/client-server-api/#device-authorisation-grant).
|
||||
items:
|
||||
type: string
|
||||
description: A grant type that the server supports.
|
||||
|
|
@ -111,10 +111,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response mode strings that the server supports at the
|
||||
authorization endpoint.
|
||||
authorisation endpoint.
|
||||
|
||||
This array MUST contain at least the `query` and `fragment` values, for
|
||||
improved security in the authorization code grant.
|
||||
improved security in the authorisation code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response mode that the server supports.
|
||||
|
|
@ -122,10 +122,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
|
||||
that the server supports at the authorization endpoint.
|
||||
that the server supports at the authorisation endpoint.
|
||||
|
||||
This array MUST contain at least the `S256` value, for improved security in
|
||||
the authorization code grant.
|
||||
the authorisation code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A PKCE code challenge method that the server supports.
|
||||
|
|
@ -133,7 +133,7 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OpenID Connect prompt values that the server supports at the
|
||||
authorization endpoint.
|
||||
authorisation endpoint.
|
||||
|
||||
Only the `create` value defined in [Initiating User Registration via OpenID
|
||||
Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
|
||||
|
|
@ -173,9 +173,9 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the device authorization endpoint, as defined in
|
||||
URL of the device authorisation endpoint, as defined in
|
||||
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use
|
||||
the [device authorization grant](/client-server-api/#device-authorization-grant).
|
||||
the [device authorisation grant](/client-server-api/#device-authorisation-grant).
|
||||
required:
|
||||
- issuer
|
||||
- authorization_endpoint
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ paths:
|
|||
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
|
||||
|
||||
If registration is successful, this endpoint will issue an access token
|
||||
the client can use to authorize itself in subsequent requests.
|
||||
the client can use to authorise itself in subsequent requests.
|
||||
|
||||
If the client does not supply a `device_id`, the server must
|
||||
auto-generate one.
|
||||
|
|
@ -167,7 +167,7 @@ paths:
|
|||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorize other requests.
|
||||
This access token can then be used to authorise other requests.
|
||||
Required if the `inhibit_login` option is false.
|
||||
refresh_token:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to get tags for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -83,7 +83,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to add a tag for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -133,7 +133,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to remove a tag for. The access token must be
|
||||
authorized to make requests for this user ID.
|
||||
authorised to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ properties:
|
|||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
Event IDs for the authorisation events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ allOf:
|
|||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
Event IDs and reference hashes for the authorisation events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ allOf:
|
|||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
Event IDs for the authorisation events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Federation Event Authorization API
|
||||
title: Matrix Federation Event Authorisation API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/event_auth/{roomId}/{eventId}":
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
"200":
|
||||
description: |-
|
||||
The fully resolved state for the room, prior to considering any state
|
||||
changes induced by the requested event. Includes the authorization
|
||||
changes induced by the requested event. Includes the authorisation
|
||||
chain for the events.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -52,8 +52,8 @@ paths:
|
|||
auth_chain:
|
||||
type: array
|
||||
description: |-
|
||||
The full set of authorization events that make up the state
|
||||
of the room, and their authorization events, recursively. Note that
|
||||
The full set of authorisation events that make up the state
|
||||
of the room, and their authorisation events, recursively. Note that
|
||||
events have a different format depending on the room version -
|
||||
check the [room version specification](/rooms) for precise event formats.
|
||||
items:
|
||||
|
|
@ -114,7 +114,7 @@ paths:
|
|||
"200":
|
||||
description: |-
|
||||
The fully resolved state for the room, prior to considering any state
|
||||
changes induced by the requested event. Includes the authorization
|
||||
changes induced by the requested event. Includes the authorisation
|
||||
chain for the events.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -124,8 +124,8 @@ paths:
|
|||
auth_chain_ids:
|
||||
type: array
|
||||
description: |-
|
||||
The full set of authorization events that make up the state
|
||||
of the room, and their authorization events, recursively.
|
||||
The full set of authorisation events that make up the state
|
||||
of the room, and their authorisation events, recursively.
|
||||
items:
|
||||
type: string
|
||||
example:
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ paths:
|
|||
}
|
||||
}
|
||||
"403":
|
||||
description: The request is not authorized. This could mean that the user is not
|
||||
description: The request is not authorised. This could mean that the user is not
|
||||
in the room.
|
||||
content:
|
||||
application/json:
|
||||
|
|
|
|||
|
|
@ -81,11 +81,11 @@ properties:
|
|||
representation of a user with sufficient power level) authorised the user's join. More
|
||||
information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
|
||||
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorisation-rules)
|
||||
of including this field in further events: in particular, the event must be signed by the
|
||||
server which owns the user ID in the field. When copying the membership event's `content`
|
||||
(for profile updates and similar) it is therefore encouraged to exclude this field in the
|
||||
copy, as otherwise the event might fail event authorization.
|
||||
copy, as otherwise the event might fail event authorisation.
|
||||
reason:
|
||||
x-addedInMatrixVersion: "1.1"
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ description: |-
|
|||
for `kick` and `ban` default to 50 if they are not specified in the
|
||||
`m.room.power_levels` event, or if the room contains no
|
||||
`m.room.power_levels` event. `invite` defaults to 0 in either case.
|
||||
Other membership values are handled during event authorization. See
|
||||
the authorization rules in [room versions](/rooms) for further details.
|
||||
Other membership values are handled during event authorisation. See
|
||||
the authorisation rules in [room versions](/rooms) for further details.
|
||||
|
||||
For redactions of a user's own events, the required power level is
|
||||
determined by the `m.room.redaction` event power level, as per `events`
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ properties:
|
|||
description: |-
|
||||
Array of redirection URIs for use in redirect-based flows.
|
||||
|
||||
At least one URI is required to use the authorization code grant.
|
||||
At least one URI is required to use the authorisation code grant.
|
||||
|
||||
The server MUST perform [validation on redirect URIs](/client-server-api/#redirect-uri-validation).
|
||||
items:
|
||||
|
|
@ -99,7 +99,7 @@ properties:
|
|||
description: |-
|
||||
Array of the OAuth 2.0 response types that the client may use.
|
||||
|
||||
This MUST include the `code` value to use the authorization code grant.
|
||||
This MUST include the `code` value to use the authorisation code grant.
|
||||
|
||||
The server MUST ignore values that it does not understand.
|
||||
items:
|
||||
|
|
@ -111,7 +111,7 @@ properties:
|
|||
Array of the OAuth 2.0 grant types that the client may use.
|
||||
|
||||
This MUST include:
|
||||
- the `authorization_code` value to use the authorization code grant,
|
||||
- the `authorisation_code` value to use the authorisation code grant,
|
||||
- the `refresh_token` value to use the refresh token grant.
|
||||
|
||||
The server MUST ignore values that it does not understand.
|
||||
|
|
|
|||
Loading…
Reference in a new issue