mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-11 21:54:10 +02:00
Compare commits
3 commits
e9526c7564
...
3a1479a48b
| Author | SHA1 | Date | |
|---|---|---|---|
|
3a1479a48b | ||
|
|
9497d3c03d | ||
|
|
572c2f3119 |
|
|
@ -1481,178 +1481,6 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
|
|||
|
||||
### OAuth 2.0 API
|
||||
|
||||
#### Server metadata discovery
|
||||
|
||||
{{% http-api spec="client-server" api="oauth_server_metadata" %}}
|
||||
|
||||
#### Scope
|
||||
|
||||
The client requests a scope in the OAuth 2.0 authorization flow, which is then
|
||||
associated to the generated access and refresh tokens. This provides a framework
|
||||
for obtaining user consent.
|
||||
|
||||
A scope is defined in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
|
||||
as a string containing a list of space-separated scope tokens.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The framework encourages the practice of obtaining additional user consent when
|
||||
a client asks for a new scope that was not granted previously. This could be
|
||||
used by future MSCs to replace the legacy [User-Interactive Authentication API](#user-interactive-authentication-api).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
##### Scope token format
|
||||
|
||||
All scope tokens related to Matrix should start with `urn:matrix:` and use the
|
||||
`:` delimiter for further sub-division.
|
||||
|
||||
Scope tokens related to mapping of Client-Server API access levels should start
|
||||
with `urn:matrix:client:`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
For MSCs that build on this namespace, unstable subdivisions should be used
|
||||
whilst in development. For example, if MSCXXXX wants to introduce the
|
||||
`urn:matrix:client:foo` scope, it could use
|
||||
`urn:matrix:client:com.example.mscXXXX.foo` during development.
|
||||
If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and
|
||||
`urn:matrix:client:bar`, it could use
|
||||
`urn:matrix:client:com.example.mscXXXX:foo` and
|
||||
`urn:matrix:client:com.example.mscXXXX:bar`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
##### Allocated scope tokens
|
||||
|
||||
This specification defines the following scope tokens:
|
||||
- [`urn:matrix:client:api:*`](#full-client-server-api-readwrite-access)
|
||||
- [`urn:matrix:client:device:<device_id>`](#device-id-allocation)
|
||||
|
||||
###### Full client-server API read/write access
|
||||
|
||||
| Scope | Purpose |
|
||||
|---------------------------|---------------------------------------------|
|
||||
| `urn:matrix:client:api:*` | Grants full access to the Client-Server API. |
|
||||
|
||||
{{% boxes/note %}}
|
||||
This token matches the behavior of the legacy authentication API. Future MSCs
|
||||
could introduce more fine-grained scope tokens like
|
||||
`urn:matrix:client:api:read:*` for read-only access.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
###### Device ID allocation
|
||||
|
||||
| Scope | Purpose |
|
||||
|----------------------------------------|----------------------------------------------------------------------------------------------|
|
||||
| `urn:matrix:client:device:<device_id>` | Allocates the given `device_id` and associates it to the generated access and refresh tokens. |
|
||||
|
||||
Contrary to the legacy login and registration APIs where the homeserver is
|
||||
typically the one generating a `device_id` and providing it to the client, with
|
||||
the OAuth 2.0 API, the client is responsible for allocating the `device_id`.
|
||||
|
||||
There MUST be exactly one `urn:matrix:client:device:<device_id>` token in the
|
||||
requested scope in the login flow.
|
||||
|
||||
When generating a new `device_id`, the client SHOULD generate a random string
|
||||
with enough entropy. It SHOULD only use characters from the unreserved character
|
||||
list defined by [RFC 3986 section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3):
|
||||
|
||||
```
|
||||
unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~"
|
||||
```
|
||||
|
||||
Using this alphabet, a 10 character string is enough to stand a sufficient
|
||||
chance of being unique per user. The homeserver MAY reject a request for a
|
||||
`device_id` that is not long enough or contains characters outside the
|
||||
unreserved list.
|
||||
|
||||
In any case it MUST only use characters allowed by the OAuth 2.0 scope
|
||||
definition in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3),
|
||||
which is defined as the following ASCII ranges:
|
||||
|
||||
```
|
||||
%x21 / %x23-5B / %x5D-7E
|
||||
```
|
||||
|
||||
This definition matches:
|
||||
- alphanumeric characters: `A-Z`, `a-z`, `0-9`
|
||||
- the following characters: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~``
|
||||
|
||||
#### Grant types
|
||||
|
||||
[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
|
||||
server metadata:
|
||||
- `token_endpoint`
|
||||
- `grant_types_supported`
|
||||
|
||||
The client must also have obtained a `client_id` by registering with the server.
|
||||
|
||||
This specification supports the following grant types:
|
||||
- [Authorization code grant](#authorization-code-grant)
|
||||
- [Refresh token grant](#refresh-token-grant)
|
||||
|
||||
##### Authorization 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
|
||||
browser redirect.
|
||||
|
||||
This grant requires the client to know the following authorization server
|
||||
metadata:
|
||||
- `authorization_endpoint`
|
||||
- `response_types_supported`
|
||||
- `response_mode_supported`
|
||||
|
||||
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 [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, strict redirect URIs.
|
||||
- Use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
|
||||
Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
|
||||
for clients with an HTTPS redirect URI.
|
||||
|
||||
###### User registration
|
||||
|
||||
Clients can signal to the server that the user desires to register a new account
|
||||
by initiating the authorization code grant with the `prompt=create` parameter
|
||||
set in the authorization 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.
|
||||
|
||||
Servers that support this parameter SHOULD show the account registration UI in
|
||||
the browser.
|
||||
|
||||
##### Refresh token grant
|
||||
|
||||
As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
|
||||
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
|
||||
token to the client in addition to the access token.
|
||||
|
||||
The access token MUST be short-lived and SHOULD be refreshed using the
|
||||
`refresh_token` when expired.
|
||||
|
||||
The homeserver SHOULD issue a new refresh token each time an old one is used,
|
||||
and invalidate the old one. However, it MUST ensure that the client is able to
|
||||
retry the refresh request in the case that the response to the request is lost.
|
||||
|
||||
The homeserver SHOULD consider that the session is compromised if an old,
|
||||
invalidated refresh token is used, and SHOULD revoke the session.
|
||||
|
||||
The client MUST handle access token refresh failures as follows:
|
||||
|
||||
- If the refresh fails due to network issues or a `5xx` HTTP status code from
|
||||
the server, the client should retry the request with the old refresh token
|
||||
later.
|
||||
- If the refresh fails due to a `4xx` HTTP status code from the server, the
|
||||
client should consider the session logged out.
|
||||
|
||||
#### Login flow
|
||||
|
||||
Logging in with the OAuth 2.0 API should be done with the [authorization code
|
||||
|
|
@ -1660,10 +1488,11 @@ grant](#authorization-code-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.
|
||||
|
||||
First, the client needs to generate the following values:
|
||||
Once the client has retrieved the [server metadata](#server-metadata-discovery),
|
||||
it needs to generate the following values:
|
||||
|
||||
- `device_id`: a unique identifier for this device; see the
|
||||
[`urn:matrix:client:device:<device_id>`] scope.
|
||||
[`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
|
||||
and the callback.
|
||||
|
|
@ -1689,7 +1518,7 @@ The client then constructs the authorization request URL using the
|
|||
| `scope` | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
|
||||
| `state` | The `state` value generated previously. |
|
||||
| `response_mode` | `fragment` or `query` (see "[Callback](#callback)" below). |
|
||||
| `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` | 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:
|
||||
|
|
@ -1820,6 +1649,178 @@ 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
|
||||
flow.
|
||||
|
||||
#### Server metadata discovery
|
||||
|
||||
{{% http-api spec="client-server" api="oauth_server_metadata" %}}
|
||||
|
||||
#### Scope
|
||||
|
||||
The client requests a scope in the OAuth 2.0 authorization flow, which is then
|
||||
associated to the generated access and refresh tokens. This provides a framework
|
||||
for obtaining user consent.
|
||||
|
||||
A scope is defined in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
|
||||
as a string containing a list of space-separated scope tokens.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The framework encourages the practice of obtaining additional user consent when
|
||||
a client asks for a new scope that was not granted previously. This could be
|
||||
used by future MSCs to replace the legacy [User-Interactive Authentication API](#user-interactive-authentication-api).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
##### Scope token format
|
||||
|
||||
All scope tokens related to Matrix should start with `urn:matrix:` and use the
|
||||
`:` delimiter for further sub-division.
|
||||
|
||||
Scope tokens related to mapping of Client-Server API access levels should start
|
||||
with `urn:matrix:client:`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
For MSCs that build on this namespace, unstable subdivisions should be used
|
||||
whilst in development. For example, if MSCXXXX wants to introduce the
|
||||
`urn:matrix:client:foo` scope, it could use
|
||||
`urn:matrix:client:com.example.mscXXXX.foo` during development.
|
||||
If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and
|
||||
`urn:matrix:client:bar`, it could use
|
||||
`urn:matrix:client:com.example.mscXXXX:foo` and
|
||||
`urn:matrix:client:com.example.mscXXXX:bar`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
##### Allocated scope tokens
|
||||
|
||||
This specification defines the following scope tokens:
|
||||
- [`urn:matrix:client:api:*`](#full-client-server-api-readwrite-access)
|
||||
- [`urn:matrix:client:device:<device_id>`](#device-id-allocation)
|
||||
|
||||
###### Full client-server API read/write access
|
||||
|
||||
| Scope | Purpose |
|
||||
|---------------------------|---------------------------------------------|
|
||||
| `urn:matrix:client:api:*` | Grants full access to the Client-Server API. |
|
||||
|
||||
{{% boxes/note %}}
|
||||
This token matches the behavior of the legacy authentication API. Future MSCs
|
||||
could introduce more fine-grained scope tokens like
|
||||
`urn:matrix:client:api:read:*` for read-only access.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
###### Device ID allocation
|
||||
|
||||
| Scope | Purpose |
|
||||
|----------------------------------------|----------------------------------------------------------------------------------------------|
|
||||
| `urn:matrix:client:device:<device_id>` | Allocates the given `device_id` and associates it to the generated access and refresh tokens. |
|
||||
|
||||
Contrary to the legacy login and registration APIs where the homeserver is
|
||||
typically the one generating a `device_id` and providing it to the client, with
|
||||
the OAuth 2.0 API, the client is responsible for allocating the `device_id`.
|
||||
|
||||
There MUST be exactly one `urn:matrix:client:device:<device_id>` token in the
|
||||
requested scope in the login flow.
|
||||
|
||||
When generating a new `device_id`, the client SHOULD generate a random string
|
||||
with enough entropy. It SHOULD only use characters from the unreserved character
|
||||
list defined by [RFC 3986 section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3):
|
||||
|
||||
```
|
||||
unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~"
|
||||
```
|
||||
|
||||
Using this alphabet, a 10 character string is enough to stand a sufficient
|
||||
chance of being unique per user. The homeserver MAY reject a request for a
|
||||
`device_id` that is not long enough or contains characters outside the
|
||||
unreserved list.
|
||||
|
||||
In any case it MUST only use characters allowed by the OAuth 2.0 scope
|
||||
definition in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3),
|
||||
which is defined as the following ASCII ranges:
|
||||
|
||||
```
|
||||
%x21 / %x23-5B / %x5D-7E
|
||||
```
|
||||
|
||||
This definition matches:
|
||||
- alphanumeric characters: `A-Z`, `a-z`, `0-9`
|
||||
- the following characters: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~``
|
||||
|
||||
#### Grant types
|
||||
|
||||
[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
|
||||
server metadata](#server-metadata-discovery):
|
||||
- `token_endpoint`
|
||||
- `grant_types_supported`
|
||||
|
||||
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)
|
||||
- [Refresh token grant](#refresh-token-grant)
|
||||
|
||||
##### Authorization 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
|
||||
browser redirect.
|
||||
|
||||
This grant requires the client to know the following [authorization server
|
||||
metadata](#server-metadata-discovery):
|
||||
- `authorization_endpoint`
|
||||
- `response_types_supported`
|
||||
- `response_mode_supported`
|
||||
|
||||
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 [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.
|
||||
- Use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
|
||||
Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
|
||||
for clients with an HTTPS redirect URI.
|
||||
|
||||
###### User registration
|
||||
|
||||
Clients can signal to the server that the user desires to register a new account
|
||||
by initiating the authorization code grant with the `prompt=create` parameter
|
||||
set in the authorization 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.
|
||||
|
||||
Servers that support this parameter SHOULD show the account registration UI in
|
||||
the browser.
|
||||
|
||||
##### Refresh token grant
|
||||
|
||||
As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
|
||||
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
|
||||
token to the client in addition to the access token.
|
||||
|
||||
The access token MUST be short-lived and SHOULD be refreshed using the
|
||||
`refresh_token` when expired.
|
||||
|
||||
The homeserver SHOULD issue a new refresh token each time an old one is used,
|
||||
and invalidate the old one. However, it MUST ensure that the client is able to
|
||||
retry the refresh request in the case that the response to the request is lost.
|
||||
|
||||
The homeserver SHOULD consider that the session is compromised if an old,
|
||||
invalidated refresh token is used, and SHOULD revoke the session.
|
||||
|
||||
The client MUST handle access token refresh failures as follows:
|
||||
|
||||
- If the refresh fails due to network issues or a `5xx` HTTP status code from
|
||||
the server, the client should retry the request with the old refresh token
|
||||
later.
|
||||
- If the refresh fails due to a `4xx` HTTP status code from the server, the
|
||||
client should consider the session logged out.
|
||||
|
||||
### Account moderation
|
||||
|
||||
#### Account locking
|
||||
|
|
|
|||
Loading…
Reference in a new issue