From 48b8a95df6b9f344d765bf6a856b8f0b21b75f7e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Oct 2019 09:41:45 -0600 Subject: [PATCH 1/2] Deprecate id_server and make it optional As per [MSC2263](https://github.com/matrix-org/matrix-doc/pull/2263) --- api/client-server/administrative_contact.yaml | 8 ++++++-- .../definitions/request_email_validation.yaml | 6 +++++- .../definitions/request_msisdn_validation.yaml | 6 +++++- api/client-server/registration.yaml | 8 ++++++-- specification/client_server_api.rst | 6 ++++++ 5 files changed, 28 insertions(+), 6 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 3581edf765d..41270535ac4 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -343,7 +343,9 @@ paths: 400: description: |- The third party identifier is already in use on the homeserver, or - the request was invalid. + 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. schema: $ref: "definitions/errors/error.yaml" examples: @@ -391,7 +393,9 @@ paths: 400: description: |- The third party identifier is already in use on the homeserver, or - the request was invalid. + 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. schema: $ref: "definitions/errors/error.yaml" examples: diff --git a/api/client-server/definitions/request_email_validation.yaml b/api/client-server/definitions/request_email_validation.yaml index 2b270514522..2d789d05156 100644 --- a/api/client-server/definitions/request_email_validation.yaml +++ b/api/client-server/definitions/request_email_validation.yaml @@ -22,6 +22,9 @@ allOf: The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. + + This parameter is deprected with a plan to be removed in a future specification + version for ``/account/password`` and ``/register`` requests. example: "id.example.com" id_access_token: type: string @@ -29,4 +32,5 @@ allOf: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. - required: ["id_server", "id_access_token"] + + Required if an ``id_server`` is supplied. diff --git a/api/client-server/definitions/request_msisdn_validation.yaml b/api/client-server/definitions/request_msisdn_validation.yaml index b013a5612a0..54988fd4ffa 100644 --- a/api/client-server/definitions/request_msisdn_validation.yaml +++ b/api/client-server/definitions/request_msisdn_validation.yaml @@ -22,6 +22,9 @@ allOf: The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification. + + This parameter is deprected with a plan to be removed in a future specification + version for ``/account/password`` and ``/register`` requests. example: "id.example.com" id_access_token: type: string @@ -29,4 +32,5 @@ allOf: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. - required: ["id_server", "id_access_token"] + + Required if an ``id_server`` is supplied. diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 733ebe4705f..a4c5bf71e35 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -425,7 +425,9 @@ paths: 400: description: |- The referenced third party identifier is not recognised by the - homeserver, or the request was invalid + 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. schema: $ref: "definitions/errors/error.yaml" examples: @@ -485,7 +487,9 @@ paths: 400: description: |- The referenced third party identifier is not recognised by the - homeserver, or the request was invalid + 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. schema: $ref: "definitions/errors/error.yaml" examples: diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 8df596be8c5..81fb28a6c79 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -809,6 +809,9 @@ To use this authentication type, clients should submit an auth dict as follows: "session": "" } +Note that ``id_server`` (and therefore ``id_access_token``) is optional if the +``/requestToken`` request did not include them. + Phone number/MSISDN-based (identity / homeserver) <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: @@ -838,6 +841,9 @@ To use this authentication type, clients should submit an auth dict as follows: "session": "" } +Note that ``id_server`` (and therefore ``id_access_token``) is optional if the +``/requestToken`` request did not include them. + Dummy Auth <<<<<<<<<< :Type: From 2e84465c13e4333f08c518db35d73c710188f6e9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Oct 2019 09:42:59 -0600 Subject: [PATCH 2/2] Changelog --- changelogs/client_server/newsfragments/2310.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2310.feature diff --git a/changelogs/client_server/newsfragments/2310.feature b/changelogs/client_server/newsfragments/2310.feature new file mode 100644 index 00000000000..0169d23b9de --- /dev/null +++ b/changelogs/client_server/newsfragments/2310.feature @@ -0,0 +1 @@ +Deprecate ``id_server`` and make it optional in several places.