Reorganize client authentication section to separate the legacy API and the new OAuth 2.0 API (#2141)
Since account locking and suspension are authentication API agnostic, this is a pre-requisite to adding the new OAuth 2.0-based API. This also splits the endpoints that where all included in the registration OpenAPI data, to separate them cleanly in the spec, and avoid having deactivation show before registration. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>pull/2158/head
Kévin Commaille
6 months ago
committed by
GitHub
parent
7470c72d94
commit
866c05f487
@ -0,0 +1 @@
|
||||
Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.
|
||||
@ -0,0 +1,141 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2022 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Account Deactivation API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/account/deactivate:
|
||||
post:
|
||||
summary: Deactivate a user's account.
|
||||
description: |-
|
||||
Deactivate the user's account, removing all ability for the user to
|
||||
login again.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided.
|
||||
|
||||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: deactivateAccount
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
id_server:
|
||||
type: string
|
||||
description: |-
|
||||
The identity server to unbind all of the user's 3PIDs from.
|
||||
If not provided, the homeserver MUST use the `id_server`
|
||||
that was originally use to bind each identifier. If the
|
||||
homeserver does not know which `id_server` that was,
|
||||
it must return an `id_server_unbind_result` of
|
||||
`no-support`.
|
||||
example: example.org
|
||||
erase:
|
||||
x-addedInMatrixVersion: "1.10"
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user would like their content to be erased as
|
||||
much as possible from the server.
|
||||
|
||||
Erasure means that any users (or servers) which join the
|
||||
room after the erasure request are served redacted copies of
|
||||
the events sent by this account. Users which had visibility
|
||||
on those events prior to the erasure are still able to see
|
||||
unredacted copies. No redactions are sent and the erasure
|
||||
request is not shared over federation, so other servers
|
||||
might still serve unredacted copies.
|
||||
|
||||
The server should additionally erase any non-event data
|
||||
associated with the user, such as [account data](/client-server-api/#client-config)
|
||||
and [contact 3PIDs](/client-server-api/#adding-account-administrative-contact-information).
|
||||
|
||||
Defaults to `false` if not present.
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The account has been deactivated.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
id_server_unbind_result:
|
||||
type: string
|
||||
enum:
|
||||
- success
|
||||
- no-support
|
||||
description: |-
|
||||
An indicator as to whether or not the homeserver was able to unbind
|
||||
the user's 3PIDs from the identity server(s). `success` indicates
|
||||
that all identifiers have been unbound from the identity server while
|
||||
`no-support` indicates that one or more identifiers failed to unbind
|
||||
due to the identity server refusing the request or the homeserver
|
||||
being unable to determine an identity server to unbind from. This
|
||||
must be `success` if the homeserver has no identifiers to unbind
|
||||
for the user.
|
||||
example: success
|
||||
required:
|
||||
- id_server_unbind_result
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
accessTokenBearer:
|
||||
$ref: definitions/security.yaml#/accessTokenBearer
|
||||
@ -0,0 +1,242 @@
|
||||
# Copyright 2016 OpenMarket Ltd
|
||||
# Copyright 2022 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Password Management API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/account/password:
|
||||
post:
|
||||
summary: Changes a user's password.
|
||||
description: |-
|
||||
Changes the password for an account on this homeserver.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api) to
|
||||
ensure the user changing the password is actually the owner of the
|
||||
account.
|
||||
|
||||
An access token should be submitted to this endpoint if the client has
|
||||
an active session.
|
||||
|
||||
The homeserver may change the flows available depending on whether a
|
||||
valid access token is provided. The homeserver SHOULD NOT revoke the
|
||||
access token provided in the request. Whether other access tokens for
|
||||
the user are revoked depends on the request parameters.
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
operationId: changePassword
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
new_password:
|
||||
type: string
|
||||
description: The new password for the account.
|
||||
example: ihatebananas
|
||||
logout_devices:
|
||||
type: boolean
|
||||
description: |-
|
||||
Whether the user's other access tokens, and their associated devices, should be
|
||||
revoked if the request succeeds. Defaults to true.
|
||||
|
||||
When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout)
|
||||
for the user's remaining devices.
|
||||
example: true
|
||||
auth:
|
||||
description: Additional authentication information for the user-interactive
|
||||
authentication API.
|
||||
allOf:
|
||||
- $ref: definitions/auth_data.yaml
|
||||
required:
|
||||
- new_password
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: The password has been changed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"401":
|
||||
description: The homeserver requires additional authentication information.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/auth_response.yaml
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/email/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given email address for the
|
||||
purpose of resetting a user's password
|
||||
description: |-
|
||||
The homeserver must check that the given email address **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/email/requestToken`](/client-server-api/#post_matrixclientv3registeremailrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given email address could be found. The server may instead send an
|
||||
email to the given address prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the email itself, either by sending a
|
||||
validation email itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordEmail
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_email_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An email was sent to the given address.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Email not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
/account/password/msisdn/requestToken:
|
||||
post:
|
||||
summary: Requests a validation token be sent to the given phone number for the
|
||||
purpose of resetting a user's password.
|
||||
description: |-
|
||||
The homeserver must check that the given phone number **is
|
||||
associated** with an account on this homeserver. This API should be
|
||||
used to request validation tokens when authenticating for the
|
||||
`/account/password` endpoint.
|
||||
|
||||
This API's parameters and response are identical to that of the
|
||||
[`/register/msisdn/requestToken`](/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)
|
||||
endpoint, except that
|
||||
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
|
||||
given phone number could be found. The server may instead send the SMS
|
||||
to the given phone number prompting the user to create an account.
|
||||
`M_THREEPID_IN_USE` may not be returned.
|
||||
|
||||
The homeserver should validate the phone number itself, either by sending a
|
||||
validation message itself or by using a service it has control over.
|
||||
operationId: requestTokenToResetPasswordMSISDN
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_msisdn_validation.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: An SMS message was sent to the given phone number.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/request_token_response.yaml
|
||||
"400":
|
||||
description: |-
|
||||
The referenced third-party identifier is not recognised by the
|
||||
homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
|
||||
can be returned if the server does not trust/support the identity server
|
||||
provided in the request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_NOT_FOUND",
|
||||
"error": "Phone number not found"
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The homeserver does not allow the third-party identifier as a
|
||||
contact option.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_THREEPID_DENIED",
|
||||
"error": "Third-party identifier is not allowed"
|
||||
}
|
||||
tags:
|
||||
- Account management
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
accessTokenBearer:
|
||||
$ref: definitions/security.yaml#/accessTokenBearer
|
||||
Loading…
Reference in New Issue