|
|
|
|
@ -292,8 +292,9 @@ and the two requests would be considered distinct because the two are
|
|
|
|
|
considered separate endpoints. Similarly, if a client logs out and back in
|
|
|
|
|
between two requests using the same transaction ID, the requests are distinct
|
|
|
|
|
because the act of logging in and out creates a new device (unless an existing
|
|
|
|
|
`device_id` is given during the [login](#login) process). On the other hand, if
|
|
|
|
|
a client re-uses a transaction ID for the same endpoint after
|
|
|
|
|
`device_id` is passed to [`POST
|
|
|
|
|
/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a
|
|
|
|
|
client re-uses a transaction ID for the same endpoint after
|
|
|
|
|
[refreshing](#refreshing-access-tokens) an access token, it will be assumed to
|
|
|
|
|
be a duplicate request and ignored. See also
|
|
|
|
|
[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices).
|
|
|
|
|
@ -435,8 +436,6 @@ endpoints it supports.
|
|
|
|
|
|
|
|
|
|
## Client Authentication
|
|
|
|
|
|
|
|
|
|
{{% changed-in v="1.15" %}} OAuth 2.0 API added to the specification.
|
|
|
|
|
|
|
|
|
|
Most API endpoints require the user to identify themselves by presenting
|
|
|
|
|
previously obtained credentials in the form of an access token.
|
|
|
|
|
An access token is typically obtained via the [Login](#login) or
|
|
|
|
|
@ -450,60 +449,6 @@ free to choose an appropriate format. Server implementors may like to
|
|
|
|
|
investigate [macaroons](http://research.google.com/pubs/pub41892.html).
|
|
|
|
|
{{% /boxes/note %}}
|
|
|
|
|
|
|
|
|
|
Since Matrix 1.15, the Client-Server specification supports two authentication
|
|
|
|
|
APIs:
|
|
|
|
|
|
|
|
|
|
* The [legacy API](#legacy-api)
|
|
|
|
|
* The [OAuth 2.0 API](#oauth-20-api)
|
|
|
|
|
|
|
|
|
|
The legacy API has existed since the first version of the Matrix specification,
|
|
|
|
|
while the OAuth 2.0 API has been introduced to rely on a industry standard and
|
|
|
|
|
its experience rather than implementing a custom protocol that might not follow
|
|
|
|
|
the best practices.
|
|
|
|
|
|
|
|
|
|
A homeserver may support one of those two APIs, or both. The two APIs are
|
|
|
|
|
mutually incompatible, which means that after logging in, clients MUST only use
|
|
|
|
|
the API that was used to obtain their current access token.
|
|
|
|
|
|
|
|
|
|
{{% boxes/note %}}
|
|
|
|
|
Currently the OAuth 2.0 API doesn't cover all the use cases of the legacy API,
|
|
|
|
|
such as automated applications that cannot use a web browser, or
|
|
|
|
|
user management by [application services](application-service-api/#server-admin-style-permissions).
|
|
|
|
|
{{% /boxes/note %}}
|
|
|
|
|
|
|
|
|
|
### Authentication API discovery
|
|
|
|
|
|
|
|
|
|
To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login)
|
|
|
|
|
endpoint can be used.
|
|
|
|
|
|
|
|
|
|
To discover if a homeserver supports the OAuth 2.0 API, the
|
|
|
|
|
[`GET /auth_metadata`](#get_matrixclientv1auth_metadata) endpoint can be used.
|
|
|
|
|
|
|
|
|
|
In both cases, the server SHOULD respond with 404 and an `M_UNRECOGNIZED` error
|
|
|
|
|
code if the corresponding API is not supported.
|
|
|
|
|
|
|
|
|
|
### Account registration
|
|
|
|
|
|
|
|
|
|
With the legacy API, a client can register a new account with the
|
|
|
|
|
[`/register`](#post_matrixclientv3register) endpoint.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### Login
|
|
|
|
|
|
|
|
|
|
With the legacy API, a client can obtain an access token by using one of the
|
|
|
|
|
[login](#legacy-login) methods supported by the homeserver at the [`POST /login`](#post_matrixclientv3login)
|
|
|
|
|
endpoint. To invalidate the access token the client must call the [`/logout`](#post_matrixclientv3logout)
|
|
|
|
|
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
|
|
|
|
|
proper [scope](#scope), as demonstrated in the [login flow](#login-flow). To
|
|
|
|
|
invalidate the access token the client must use [token revocation](#token-revocation).
|
|
|
|
|
|
|
|
|
|
### Using access tokens
|
|
|
|
|
|
|
|
|
|
Access tokens may be provided via a request header, using the Authentication
|
|
|
|
|
@ -549,14 +494,12 @@ used to generate a new access token and refresh token, the new access
|
|
|
|
|
and refresh tokens are now bound to the device associated with the
|
|
|
|
|
initial refresh token.
|
|
|
|
|
|
|
|
|
|
During login or registration, the generated access token should be associated
|
|
|
|
|
with a `device_id`. The legacy [Login](#legacy-login) and [Registration](#legacy-account-registration)
|
|
|
|
|
processes auto-generate a new `device_id`, but a client is also free to provide
|
|
|
|
|
its own `device_id`. With the OAuth 2.0 API, the `device_id` is always provided
|
|
|
|
|
by the client. The client can generate a new `device_id` or, provided the user
|
|
|
|
|
remains the same, reuse an existing device. If the client sets the `device_id`,
|
|
|
|
|
the server will invalidate any access and refresh tokens previously assigned to
|
|
|
|
|
that device.
|
|
|
|
|
By default, the [Login](#login) and [Registration](#account-registration)
|
|
|
|
|
processes auto-generate a new `device_id`. A client is also free to
|
|
|
|
|
generate its own `device_id` or, provided the user remains the same,
|
|
|
|
|
reuse a device: in either case the client should pass the `device_id` in
|
|
|
|
|
the request body. If the client sets the `device_id`, the server will
|
|
|
|
|
invalidate any access and refresh tokens previously assigned to that device.
|
|
|
|
|
|
|
|
|
|
### Refreshing access tokens
|
|
|
|
|
|
|
|
|
|
@ -565,13 +508,14 @@ that device.
|
|
|
|
|
Access tokens can expire after a certain amount of time. Any HTTP calls that
|
|
|
|
|
use an expired access token will return with an error code `M_UNKNOWN_TOKEN`,
|
|
|
|
|
preferably with `soft_logout: true`. When a client receives this error and it
|
|
|
|
|
has a refresh token, it should attempt to refresh the access token. Clients can
|
|
|
|
|
also refresh their access token at any time, even if it has not yet expired. If
|
|
|
|
|
the token refresh succeeds, the client should use the new token for future
|
|
|
|
|
requests, and can re-try previously-failed requests with the new token. When an
|
|
|
|
|
access token is refreshed, a new refresh token may be returned; if a new refresh
|
|
|
|
|
token is given, the old refresh token will be invalidated, and the new refresh
|
|
|
|
|
token should be used when the access token needs to be refreshed.
|
|
|
|
|
has a refresh token, it should attempt to refresh the access token by calling
|
|
|
|
|
[`/refresh`](#post_matrixclientv3refresh). Clients can also refresh their
|
|
|
|
|
access token at any time, even if it has not yet expired. If the token refresh
|
|
|
|
|
succeeds, the client should use the new token for future requests, and can
|
|
|
|
|
re-try previously-failed requests with the new token. When an access token is
|
|
|
|
|
refreshed, a new refresh token may be returned; if a new refresh token is
|
|
|
|
|
given, the old refresh token will be invalidated, and the new refresh token
|
|
|
|
|
should be used when the access token needs to be refreshed.
|
|
|
|
|
|
|
|
|
|
The old refresh token remains valid until the new access token or refresh token
|
|
|
|
|
is used, at which point the old refresh token is revoked. This ensures that if
|
|
|
|
|
@ -584,7 +528,6 @@ and attempt to obtain a new access token by re-logging in. If the error
|
|
|
|
|
response does not include a `soft_logout: true` property, the client should
|
|
|
|
|
consider the user as being logged out.
|
|
|
|
|
|
|
|
|
|
With the legacy API, refreshing access tokens is done by calling [`/refresh`](#post_matrixclientv3refresh).
|
|
|
|
|
Handling of clients that do not support refresh tokens is up to the homeserver;
|
|
|
|
|
clients indicate their support for refresh tokens by including a
|
|
|
|
|
`refresh_token: true` property in the request body of the
|
|
|
|
|
@ -594,11 +537,6 @@ may allow the use of non-expiring access tokens, or may expire access tokens
|
|
|
|
|
anyways and rely on soft logout behaviour on clients that don't support
|
|
|
|
|
refreshing.
|
|
|
|
|
|
|
|
|
|
With the OAuth 2.0 API, refreshing access tokens is done with the [refresh token
|
|
|
|
|
grant type](#refresh-token-grant), as demonstrated in the [token refresh
|
|
|
|
|
flow](#token-refresh-flow). Support for refreshing access tokens is mandatory
|
|
|
|
|
with this API.
|
|
|
|
|
|
|
|
|
|
### Soft logout
|
|
|
|
|
|
|
|
|
|
A client can be in a "soft logout" state if the server requires
|
|
|
|
|
@ -622,24 +560,8 @@ specifying the device ID it is already using to the login API.
|
|
|
|
|
with an `M_USER_LOCKED` error code, cannot obtain a new access token until
|
|
|
|
|
the account has been [unlocked](#account-locking).
|
|
|
|
|
|
|
|
|
|
### Account management
|
|
|
|
|
|
|
|
|
|
With the legacy API, a client can use several endpoints to allow the user to
|
|
|
|
|
manage their account like [changing their password](#password-management),
|
|
|
|
|
[managing their devices](#device-management) or
|
|
|
|
|
[deactivating their account](#account-deactivation).
|
|
|
|
|
|
|
|
|
|
With the OAuth 2.0 API, all account management is done via the homeserver's web
|
|
|
|
|
UI.
|
|
|
|
|
|
|
|
|
|
### Legacy API
|
|
|
|
|
|
|
|
|
|
This is the original authentication API that was introduced in the first version
|
|
|
|
|
of the Client-Server specification and uses custom APIs. Contrary to the OAuth
|
|
|
|
|
2.0 API, account management is primarily done in the client's interface and as
|
|
|
|
|
such it does not usually require the end user to be redirected to a web UI in
|
|
|
|
|
their browser.
|
|
|
|
|
|
|
|
|
|
#### User-Interactive Authentication API
|
|
|
|
|
|
|
|
|
|
##### Overview
|
|
|
|
|
@ -1407,7 +1329,7 @@ The `country` is the two-letter uppercase ISO-3166-1 alpha-2 country
|
|
|
|
|
code that the number in `phone` should be parsed as if it were dialled
|
|
|
|
|
from.
|
|
|
|
|
|
|
|
|
|
#### Login {id="legacy-login"}
|
|
|
|
|
#### Login
|
|
|
|
|
|
|
|
|
|
A client can obtain access tokens using the [`/login`](#post_matrixclientv3login) API.
|
|
|
|
|
|
|
|
|
|
@ -1536,11 +1458,11 @@ forwarded to the login endpoint during the login process. For example:
|
|
|
|
|
|
|
|
|
|
GET /_matrix/static/client/login/?device_id=GHTYAJCE
|
|
|
|
|
|
|
|
|
|
#### Account registration {id="legacy-account-registration"}
|
|
|
|
|
#### Account registration
|
|
|
|
|
|
|
|
|
|
{{% http-api spec="client-server" api="registration" %}}
|
|
|
|
|
|
|
|
|
|
#### Account management {id="legacy-account-management"}
|
|
|
|
|
#### Account management
|
|
|
|
|
|
|
|
|
|
##### Password management
|
|
|
|
|
|
|
|
|
|
@ -1559,205 +1481,6 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
|
|
|
|
|
|
|
|
|
|
### OAuth 2.0 API
|
|
|
|
|
|
|
|
|
|
{{% added-in v="1.15" %}}
|
|
|
|
|
|
|
|
|
|
Contrary to the legacy API that uses custom endpoints and UIA, this
|
|
|
|
|
authentication API is based on the [OAuth 2.0](https://oauth.net/2/) industry
|
|
|
|
|
standard introduced in [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
|
|
|
|
|
and extended by other RFCs, with a few features from [OpenID Connect](https://openid.net/connect/).
|
|
|
|
|
This allows us to benefit from its experience and from any further enhancements
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
because they don't have access to the user's credentials anymore.
|
|
|
|
|
|
|
|
|
|
{{% boxes/warning %}}
|
|
|
|
|
The [User-Interactive Authentication API](#user-interactive-authentication-api)
|
|
|
|
|
is not compatible with the OAuth 2.0 API, so the endpoints that depend on it for
|
|
|
|
|
authentication can't be used when an access token is obtained with this API.
|
|
|
|
|
{{% /boxes/warning %}}
|
|
|
|
|
|
|
|
|
|
**Sample flow**
|
|
|
|
|
|
|
|
|
|
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-flow) by authorizing a [scope](#scope) for the client with the [authorization code grant](#authorization-code-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 flow
|
|
|
|
|
|
|
|
|
|
Logging in with the OAuth 2.0 API should be done with the [authorization code
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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>`](#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.
|
|
|
|
|
- `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.
|
|
|
|
|
|
|
|
|
|
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**
|
|
|
|
|
|
|
|
|
|
The client then constructs the authorization request URL using the
|
|
|
|
|
`authorization_endpoint` value, with the following query parameters:
|
|
|
|
|
|
|
|
|
|
| Parameter | Value |
|
|
|
|
|
|-------------------------|----------------------------------------------------|
|
|
|
|
|
| `response_type` | `code` |
|
|
|
|
|
| `client_id` | The client ID returned from client registration. |
|
|
|
|
|
| `redirect_uri` | The redirect URI that MUST match one of the values registered in the client metadata |
|
|
|
|
|
| `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_method` | `S256` |
|
|
|
|
|
|
|
|
|
|
This authorization 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.
|
|
|
|
|
- For native clients, this can be done by opening the URL using the system
|
|
|
|
|
browser, or, when available, through platform-specific APIs such as
|
|
|
|
|
[`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:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
https://account.example.com/oauth2/auth?
|
|
|
|
|
client_id = s6BhdRkqt3 &
|
|
|
|
|
response_type = code &
|
|
|
|
|
response_mode = fragment &
|
|
|
|
|
redirect_uri = https://app.example.com/oauth2-callback &
|
|
|
|
|
scope = urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD &
|
|
|
|
|
state = ewubooN9weezeewah9fol4oothohroh3 &
|
|
|
|
|
code_challenge = 72xySjpngTcCxgbPfFmkPHjMvVDl2jW1aWP7-J6rmwU &
|
|
|
|
|
code_challenge_method = S256
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<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.
|
|
|
|
|
Whether the parameters are in the URL fragment or query parameters is determined
|
|
|
|
|
by the `response_mode` value:
|
|
|
|
|
|
|
|
|
|
- If set to `fragment`, the parameters will be placed in the URL fragment, like
|
|
|
|
|
`https://example.com/callback#param1=value1¶m2=value2`.
|
|
|
|
|
- If set to `query`, the parameters will be in placed the query string, like
|
|
|
|
|
`com.example.app:/callback?param1=value1¶m2=value2`.
|
|
|
|
|
|
|
|
|
|
To avoid disclosing the parameters to the web server hosting the `redirect_uri`,
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
A successful authorization will have a `code` value, for example:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
A failed authorization will have the following values:
|
|
|
|
|
|
|
|
|
|
- `error`: the error code
|
|
|
|
|
- `error_description`: the error description (optional)
|
|
|
|
|
- `error_uri`: the URI where the user can find more information about the error (optional)
|
|
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&error_uri=https%3A%2F%2Ferrors.example.com%2F
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Token request**
|
|
|
|
|
|
|
|
|
|
The client then exchanges the authorization 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
|
|
|
|
|
parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
|
|
|
|
|
|
|
|
|
| Parameter | Value |
|
|
|
|
|
|-----------------|------------------------------------------------------------|
|
|
|
|
|
| `grant_type` | `authorization_code` |
|
|
|
|
|
| `code` | The value of `code` obtained from the callback. |
|
|
|
|
|
| `redirect_uri` | The same `redirect_uri` used in the authorization request. |
|
|
|
|
|
| `client_id` | The client ID returned from client registration. |
|
|
|
|
|
| `code_verifier` | The value generated at the start of the authorization flow. |
|
|
|
|
|
|
|
|
|
|
The server replies with a JSON object containing the access token, the token
|
|
|
|
|
type, the expiration time, and the refresh token.
|
|
|
|
|
|
|
|
|
|
Sample token request:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
POST /oauth2/token HTTP/1.1
|
|
|
|
|
Host: account.example.com
|
|
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
|
Accept: application/json
|
|
|
|
|
|
|
|
|
|
grant_type=authorization_code
|
|
|
|
|
&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
|
|
|
|
|
&redirect_uri=https://app.example.com/oauth2-callback
|
|
|
|
|
&client_id=s6BhdRkqt3
|
|
|
|
|
&code_verifier=ogie4iVaeteeKeeLaid0aizuimairaCh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Sample response:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"access_token": "2YotnFZFEjr1zCsicMWpAA",
|
|
|
|
|
"token_type": "Bearer",
|
|
|
|
|
"expires_in": 299,
|
|
|
|
|
"refresh_token": "tGz3JOkF0XG5Qx2TlKWIA",
|
|
|
|
|
"scope": "urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
|
|
|
|
|
endpoint to get the user ID that owns the access token.
|
|
|
|
|
|
|
|
|
|
#### Token refresh flow
|
|
|
|
|
|
|
|
|
|
Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
|
|
|
|
|
grant](#refresh-token-grant).
|
|
|
|
|
|
|
|
|
|
When the access token expires, the client must refresh it by making a `POST`
|
|
|
|
|
request to the `token_endpoint` with the following parameters, encoded as
|
|
|
|
|
`application/x-www-form-urlencoded` in the body:
|
|
|
|
|
|
|
|
|
|
| Parameter | Value |
|
|
|
|
|
|-----------------|------------------------------------------------------------|
|
|
|
|
|
| `grant_type` | `refresh_token` |
|
|
|
|
|
| `refresh_token` | The `refresh_token` obtained from the token response during the last token request. |
|
|
|
|
|
| `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
|
|
|
|
|
flow.
|
|
|
|
|
|
|
|
|
|
#### Server metadata discovery
|
|
|
|
|
|
|
|
|
|
{{% http-api spec="client-server" api="oauth_server_metadata" %}}
|
|
|
|
|
@ -2055,162 +1778,6 @@ 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.
|
|
|
|
|
|
|
|
|
|
#### Token revocation
|
|
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
|
|
The body of the request includes the following parameters, encoded as
|
|
|
|
|
`application/x-www-form-urlencoded`:
|
|
|
|
|
|
|
|
|
|
<table>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Parameter</th>
|
|
|
|
|
<th>Value</th>
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody>
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>token</code></td>
|
|
|
|
|
<td>
|
|
|
|
|
<strong>Required.</strong> MUST contain either the access token or the
|
|
|
|
|
refresh token to be revoked.
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>token_type_hint</code></td>
|
|
|
|
|
<td>
|
|
|
|
|
<strong>Optional.</strong> If present, MUST have a value of either
|
|
|
|
|
<code>access_token</code> or <code>refresh_token</code>. The server MAY
|
|
|
|
|
use this value to optimize the token lookup process.
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td><code>client_id</code></td>
|
|
|
|
|
<td>
|
|
|
|
|
<p>
|
|
|
|
|
<strong>Optional.</strong> The client identifier obtained during
|
|
|
|
|
<a href="#client-registration">client registration</a>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the <code>client_id</code> is not provided, or does not match the
|
|
|
|
|
client associated with the token, the server SHOULD still revoke the
|
|
|
|
|
token. This behavior is meant to help good actors like secret scanning
|
|
|
|
|
tools to proactively revoke leaked tokens. The server MAY also warn
|
|
|
|
|
the user that one of their sessions may be compromised in this
|
|
|
|
|
scenario.
|
|
|
|
|
</p>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</tbody>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
For example, revoking using the access token:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
POST /oauth2/revoke HTTP/1.1
|
|
|
|
|
Host: auth.example.com
|
|
|
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
|
|
|
|
|
|
token=mat_ooreiPhei2wequu9fohkai3AeBaec9oo&
|
|
|
|
|
token_type_hint=access_token&
|
|
|
|
|
client_id=s6BhdRkqt3
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The server MUST revoke both the access token and refresh token associated with
|
|
|
|
|
the token provided in the request.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
`401 Unauthorized` response
|
|
|
|
|
- For other errors, the server returns a `400 Bad Request` response with error
|
|
|
|
|
details
|
|
|
|
|
|
|
|
|
|
### Account moderation
|
|
|
|
|
|
|
|
|
|
#### Account locking
|
|
|
|
|
|
