From 31481840525620c8ac657d31956cfa9428f8f2b0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 10:58:43 +0100 Subject: [PATCH 01/21] HS' can send 3PID token. Add a new submit_url field --- api/client-server/administrative_contact.yaml | 116 +++++++++++-- api/client-server/registration.yaml | 162 ++++++++++++++---- 2 files changed, 228 insertions(+), 50 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 33ea9786..d62a4fab 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -132,11 +132,30 @@ paths: } responses: 200: - description: The addition was successful. + description: |- + The addition was successful. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. examples: - application/json: {} + application/json: { + "submit_url": "https://example.org/path/to/submitToken" + } schema: type: object + properties: + submit_url: + type: string + description: |- + An optional URL to submit information to to verify a + third-party identifier. + example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. examples: @@ -187,12 +206,14 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks that the given email address is **not** already associated - with an account on this homeserver. This API should be used to request - validation tokens when adding an email address to an account. This API's - parameters and response are identical to that of the |/register/email/requestToken|_ - endpoint. + The homeserver should check that the given email address is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding an email address to an + account. This API's parameters and response are identical to that of + the |/register/email/requestToken|_ endpoint. The homeserver has the + choice of validating the email address itself, or proxying the request + to the ``validate/email/requestToken`` Identity Server API on the + server sent in ``id_server``. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -212,9 +233,38 @@ paths: required: ['id_server'] responses: 200: - description: An email was sent to the given address. + description: |- + An email was sent to the given address. + Note that this may be an email containing the validation token or + it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a @@ -241,12 +291,14 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks that the given phone number is **not** already associated - with an account on this homeserver. This API should be used to request - validation tokens when adding a phone number to an account. This API's - parameters and response are identical to that of the |/register/msisdn/requestToken|_ - endpoint. + The homeserver should check that the given phone number is **not** + already associated with an account on this homeserver. This API should + be used to request validation tokens when adding a phone number to an + account. This API's parameters and response are identical to that of + the |/register/msisdn/requestToken|_ endpoint. The homeserver has the + choice of validating the phone number itself, or proxying the request + to the ``validate/msisdn/requestToken`` Identity Server API on the + server sent in ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -266,9 +318,37 @@ paths: required: ['id_server'] responses: 200: - description: An SMS message was sent to the given phone number. + description: |- + An SMS message was sent to the given phone number. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/msisdn/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" + 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3195ab41..00d2e90f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -204,10 +204,11 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks that the given email address is not already associated - with an account on this homeserver. See the Identity Service API for - further information. + The homeserver should check that the given email address is **not** + already associated with an account on this homeserver. The homeserver + has the choice of validating the email address itself, or proxying the + request to the ``validate/email/requestToken`` Identity Server API on + the server sent in ``id_server``. operationId: requestTokenToRegisterEmail parameters: - in: body @@ -231,8 +232,34 @@ paths: An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: The homeserver does not permit the address to be bound. schema: @@ -264,10 +291,11 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks that the given phone number is not already associated - with an account on this homeserver. See the Identity Service API for - further information. + The homeserver should check that the given phone number is **not** + already associated with an account on this homeserver. The homeserver + has the choice of validating the phone number itself, or proxying the + request to the ``validate/msisdn/requestToken`` Identity Server API on + the server sent in ``id_server``. operationId: requestTokenToRegisterMSISDN parameters: - in: body @@ -291,8 +319,34 @@ paths: An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. + + ``submit_url`` is an optional field containing a URL where the + client must submit a validation token to, with identical parameters + to the Identity Service API's ``/validate/msisdn/submitToken`` + endpoint. The homeserver will send this token to the user, which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client + must submit a validation token to, with identical + parameters to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: The homeserver does not permit the address to be bound. schema: @@ -377,16 +431,21 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - Proxies the Identity Service API ``validate/email/requestToken``, but - first checks 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 HS API |/register/email/requestToken|_ 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 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 HS API + |/register/email/requestToken|_ 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 has the choice of validating the email address itself, + or proxying the request to the ``validate/email/requestToken`` Identity + server api on the server sent in ``id_server``. .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -412,7 +471,24 @@ paths: 200: description: An email was sent to the given address. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit a validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a @@ -439,16 +515,21 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - Proxies the Identity Service API ``validate/msisdn/requestToken``, but - first checks 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 HS API |/register/msisdn/requestToken|_ 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 an - SMS message to the given address prompting the user to create an account. - `M_THREEPID_IN_USE` may not be returned. + The homeserver should 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 HS API + |/register/msisdn/requestToken|_ 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 has the choice of validating the phone number itself, or + proxying the request to the ``validate/msisdn/requestToken`` Identity + server api on the server sent in ``id_server``. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` @@ -474,7 +555,24 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "../identity/definitions/sid.yaml" + allOf: + - $ref: "../identity/definitions/sid.yaml" + - type: object + properties: + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit a validation token to, with identical parameters + to the Identity Service API's + ``/validate/msisdn/submitToken`` endpoint. The homeserver + will send this token to the user, which should then be + prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" 403: description: |- The homeserver does not allow the third party identifier as a From 8a6ef187db803e8150670b6b3b16a496eccfd9db Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 17:52:17 +0100 Subject: [PATCH 02/21] more object! --- api/client-server/administrative_contact.yaml | 2 ++ api/client-server/registration.yaml | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 71ea3e6a..c2985f66 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -272,6 +272,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -355,6 +356,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c8afed83..769614c1 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -248,6 +248,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -335,6 +336,7 @@ paths: If this field is not present, the client can assume that verification will happen without the client's involvement. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -477,6 +479,7 @@ paths: 200: description: An email was sent to the given address. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object @@ -561,6 +564,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: + type: object allOf: - $ref: "../identity/definitions/sid.yaml" - type: object From a8edb066aa52bdadff63c2fa9d9b5ad50a8f5b99 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 Jun 2019 18:00:12 +0100 Subject: [PATCH 03/21] Clear up some wording --- api/client-server/registration.yaml | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 769614c1..d97766e2 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -213,8 +213,10 @@ paths: The homeserver should check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Server API on - the server sent in ``id_server``. + request to the ``validate/email/requestToken`` Identity Server API. The + request should be proxied to the domain that is sent by the client in + the ``id_server``. It is imperative that the homeserver keep a list of + trusted Identity Servers and only proxies to those it trusts. operationId: requestTokenToRegisterEmail parameters: - in: body @@ -301,8 +303,10 @@ paths: The homeserver should check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Server API on - the server sent in ``id_server``. + request to the ``validate/msisdn/requestToken`` Identity Server API. The + request should be proxied to the domain that is sent by the client in + the ``id_server``. It is imperative that the homeserver keep a list of + trusted Identity Servers and only proxies to those it trusts. operationId: requestTokenToRegisterMSISDN parameters: - in: body @@ -453,7 +457,11 @@ paths: The homeserver has the choice of validating the email address itself, or proxying the request to the ``validate/email/requestToken`` Identity - server api on the server sent in ``id_server``. + Server API. The request should be proxied to the domain that is sent by + the client in the ``id_server``. It is imperative that the homeserver + keep a list of trusted Identity Servers and only proxies to those it + trusts. + .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -536,9 +544,12 @@ paths: prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the phone number itself, or - proxying the request to the ``validate/msisdn/requestToken`` Identity - server api on the server sent in ``id_server``. + The homeserver has the choice of validating the phone number itself, + or proxying the request to the ``validate/msisdn/requestToken`` Identity + Server API. The request should be proxied to the domain that is sent by + the client in the ``id_server``. It is imperative that the homeserver + keep a list of trusted Identity Servers and only proxies to those it + trusts. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` From 1776ba28d3d98d3a63c7b7becc032621aab9632b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sat, 8 Jun 2019 18:52:38 +0100 Subject: [PATCH 04/21] Address review comments --- api/client-server/administrative_contact.yaml | 70 +++++--------- api/client-server/registration.yaml | 94 ++++++++----------- 2 files changed, 63 insertions(+), 101 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c2985f66..bc6f98c7 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -134,15 +134,6 @@ paths: 200: description: |- The addition was successful. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. examples: application/json: { "submit_url": "https://example.org/path/to/submitToken" @@ -153,8 +144,15 @@ paths: submit_url: type: string description: |- - An optional URL to submit information to to verify a - third-party identifier. + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's involvement. example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. @@ -231,14 +229,14 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - The homeserver should check that the given email address is **not** + The homeserver must check that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request - to the ``validate/email/requestToken`` Identity Server API on the - server sent in ``id_server``. + to the ``validate/email/requestToken`` Identity Service API as + identified by ``id_server``. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -262,15 +260,6 @@ paths: An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. schema: type: object allOf: @@ -280,11 +269,11 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be + must send this token to the user, which should then be prompted to provide it to the client. If this field is not present, the client can assume that @@ -317,14 +306,14 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - The homeserver should check that the given phone number is **not** + The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request - to the ``validate/msisdn/requestToken`` Identity Server API on the - server sent in ``id_server``. + to the ``validate/msisdn/requestToken`` Identity Service API as + identified by ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -345,16 +334,7 @@ paths: responses: 200: description: |- - An SMS message was sent to the given phone number. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/msisdn/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. + A SMS message was sent to the given phone number. schema: type: object allOf: @@ -364,12 +344,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index d97766e2..c8615d29 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -210,10 +210,10 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - The homeserver should check that the given email address is **not** + The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Server API. The + request to the ``validate/email/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -240,15 +240,6 @@ paths: An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/email/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. schema: type: object allOf: @@ -258,12 +249,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -300,10 +291,10 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - The homeserver should check that the given phone number is **not** + The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Server API. The + request to the ``validate/msisdn/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -327,18 +318,9 @@ paths: responses: 200: description: |- - An SMS message has been sent to the specified phone number. - Note that this may be an SMS message containing the validation token or it may be informing - the user of an error. - - ``submit_url`` is an optional field containing a URL where the - client must submit a validation token to, with identical parameters - to the Identity Service API's ``/validate/msisdn/submitToken`` - endpoint. The homeserver will send this token to the user, which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's involvement. + A SMS message has been sent to the specified phone number. Note + that this may be an SMS message containing the validation token or + it may be informing the user of an error. schema: type: object allOf: @@ -348,12 +330,12 @@ paths: submit_url: type: string description: |- - An optional field containing a URL where the client - must submit a validation token to, with identical - parameters to the Identity Service API's + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -443,17 +425,17 @@ paths: 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 should check that the given email address **is + 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 HS API - |/register/email/requestToken|_ 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. + This API's parameters and response are identical to that of the + |/register/email/requestToken|_ 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 has the choice of validating the email address itself, or proxying the request to the ``validate/email/requestToken`` Identity @@ -496,11 +478,11 @@ paths: type: string description: |- An optional field containing a URL where the client must - submit a validation token to, with identical parameters + submit the validation token to, with identical parameters to the Identity Service API's ``/validate/email/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's @@ -532,17 +514,17 @@ paths: 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 should check that the given phone number **is + 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 HS API - |/register/msisdn/requestToken|_ 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. + This API's parameters and response are identical to that of the + |/register/msisdn/requestToken|_ 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 has the choice of validating the phone number itself, or proxying the request to the ``validate/msisdn/requestToken`` Identity @@ -573,7 +555,7 @@ paths: required: ['id_server'] responses: 200: - description: An SMS message was sent to the given phone number. + description: A SMS message was sent to the given phone number. schema: type: object allOf: @@ -584,11 +566,11 @@ paths: type: string description: |- An optional field containing a URL where the client must - submit a validation token to, with identical parameters + submit the validation token to, with identical parameters to the Identity Service API's ``/validate/msisdn/submitToken`` endpoint. The homeserver - will send this token to the user, which should then be - prompted to provide it to the client. + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's From 0ded48427652857f92e323d5d85580adf0b6c7bd Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 16:10:44 +0100 Subject: [PATCH 05/21] Address review comments --- api/client-server/administrative_contact.yaml | 4 ++-- api/client-server/registration.yaml | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index bc6f98c7..99451294 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -235,7 +235,7 @@ paths: account. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request - to the ``validate/email/requestToken`` Identity Service API as + to the ``/validate/email/requestToken`` Identity Service API as identified by ``id_server``. operationId: requestTokenTo3PIDEmail parameters: @@ -312,7 +312,7 @@ paths: account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request - to the ``validate/msisdn/requestToken`` Identity Service API as + to the ``/validate/msisdn/requestToken`` Identity Service API as identified by ``id_server``. operationId: requestTokenTo3PIDMSISDN parameters: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c8615d29..21626815 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -213,7 +213,7 @@ paths: The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the email address itself, or proxying the - request to the ``validate/email/requestToken`` Identity Service API. The + request to the ``/validate/email/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -294,7 +294,7 @@ paths: The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver has the choice of validating the phone number itself, or proxying the - request to the ``validate/msisdn/requestToken`` Identity Service API. The + request to the ``/validate/msisdn/requestToken`` Identity Service API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it trusts. @@ -428,7 +428,7 @@ paths: 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. + ``/account/password`` endpoint. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint, except that @@ -438,7 +438,7 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the email address itself, - or proxying the request to the ``validate/email/requestToken`` Identity + or proxying the request to the ``/validate/email/requestToken`` Identity Server API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it @@ -517,7 +517,7 @@ paths: 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. + ``/account/password`` endpoint. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint, except that @@ -527,7 +527,7 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the phone number itself, - or proxying the request to the ``validate/msisdn/requestToken`` Identity + or proxying the request to the ``/validate/msisdn/requestToken`` Identity Server API. The request should be proxied to the domain that is sent by the client in the ``id_server``. It is imperative that the homeserver keep a list of trusted Identity Servers and only proxies to those it From fba61941af471e885fb2310ddb443660e92f0929 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:02:57 +0100 Subject: [PATCH 06/21] Move submit_url responses to ref --- api/client-server/administrative_contact.yaml | 41 +--------- api/client-server/registration.yaml | 80 +------------------ api/identity/definitions/sid.yaml | 14 ++++ 3 files changed, 20 insertions(+), 115 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 99451294..d26e5a96 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -261,25 +261,7 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user, which should then be - prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -336,26 +318,7 @@ paths: description: |- A SMS message was sent to the given phone number. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" - + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 21626815..a2a0d47f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,25 +241,7 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -322,25 +304,7 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -469,25 +433,7 @@ paths: 200: description: An email was sent to the given address. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -557,25 +503,7 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - type: object - allOf: - - $ref: "../identity/definitions/sid.yaml" - - type: object - properties: - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/msisdn/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" + - $ref: "../identity/definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index c1f1ae64..c09ed395 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -21,4 +21,18 @@ properties: ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they must not be empty. example: "123abc" + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" required: ['sid'] From 525bedf8e14327556153d19933efcd488fa61017 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:10:44 +0100 Subject: [PATCH 07/21] Fix refs --- api/client-server/administrative_contact.yaml | 6 ++++-- api/client-server/registration.yaml | 12 ++++++++---- api/identity/definitions/sid.yaml | 14 -------------- 3 files changed, 12 insertions(+), 20 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index d26e5a96..c19872e8 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -261,7 +261,8 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -318,7 +319,8 @@ paths: description: |- A SMS message was sent to the given phone number. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a2a0d47f..4ea8b252 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,7 +241,8 @@ paths: Note that this may be an email containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -304,7 +305,8 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -433,7 +435,8 @@ paths: 200: description: An email was sent to the given address. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -503,7 +506,8 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - - $ref: "../identity/definitions/sid.yaml" + type: object + $ref: "definitions/sid.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index c09ed395..c1f1ae64 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -21,18 +21,4 @@ properties: ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they must not be empty. example: "123abc" - submit_url: - type: string - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. - - If this field is not present, the client can assume that - verification will happen without the client's - involvement. - example: "https://example.org/path/to/submitToken" required: ['sid'] From 2551ff6ce0b4100a3436344c2043241998635fa0 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 20:12:23 +0100 Subject: [PATCH 08/21] Actually check in code --- api/client-server/definitions/sid.yaml | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 api/client-server/definitions/sid.yaml diff --git a/api/client-server/definitions/sid.yaml b/api/client-server/definitions/sid.yaml new file mode 100644 index 00000000..50b45ca9 --- /dev/null +++ b/api/client-server/definitions/sid.yaml @@ -0,0 +1,38 @@ +# Copyright 2019 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. +type: object +properties: + sid: + type: string + description: |- + The session ID. Session IDs are opaque strings generated by the identity + server. They must consist entirely of the characters + ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they + must not be empty. + example: "123abc" + submit_url: + type: string + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's + ``/validate/email/submitToken`` endpoint. The homeserver + must send this token to the user (if applicable), which + should then be prompted to provide it to the client. + + If this field is not present, the client can assume that + verification will happen without the client's + involvement. + example: "https://example.org/path/to/submitToken" +required: ['sid'] From 046a83448862d000048b644386cfacd5df6190e3 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Sun, 9 Jun 2019 22:04:58 +0100 Subject: [PATCH 09/21] Slight code cleanup --- api/client-server/administrative_contact.yaml | 14 +++++--------- api/client-server/registration.yaml | 12 ++++-------- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c19872e8..f0a86762 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -132,8 +132,7 @@ paths: } responses: 200: - description: |- - The addition was successful. + description: The addition was successful. examples: application/json: { "submit_url": "https://example.org/path/to/submitToken" @@ -257,11 +256,10 @@ paths: responses: 200: description: |- - An email was sent to the given address. - Note that this may be an email containing the validation token or - it may be informing the user of an error. + An email was sent to the given address. Note that this may be an + email containing the validation token or it may be informing the + user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- @@ -316,10 +314,8 @@ paths: required: ['id_server'] responses: 200: - description: |- - A SMS message was sent to the given phone number. + description: A SMS message was sent to the given phone number. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 4ea8b252..c892b08d 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -237,11 +237,10 @@ paths: responses: 200: description: |- - An email has been sent to the specified address. - Note that this may be an email containing the validation token or it may be informing - the user of an error. + An email has been sent to the specified address. Note that this + may be an email containing the validation token or it may be + informing the user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. @@ -301,11 +300,10 @@ paths: responses: 200: description: |- - A SMS message has been sent to the specified phone number. Note + A SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - type: object $ref: "definitions/sid.yaml" 403: description: The homeserver does not permit the address to be bound. @@ -435,7 +433,6 @@ paths: 200: description: An email was sent to the given address. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- @@ -506,7 +503,6 @@ paths: 200: description: A SMS message was sent to the given phone number. schema: - type: object $ref: "definitions/sid.yaml" 403: description: |- From fe23de7d7f43f6d7ed30f0a9a320b940071e89f9 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 05:20:15 +0100 Subject: [PATCH 10/21] A SMS -> An SMS --- api/client-server/administrative_contact.yaml | 2 +- api/client-server/registration.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index f0a86762..4c1ea2e7 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -314,7 +314,7 @@ paths: required: ['id_server'] responses: 200: - description: A SMS message was sent to the given phone number. + description: An SMS message was sent to the given phone number. schema: $ref: "definitions/sid.yaml" 403: diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index c892b08d..00334434 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -300,7 +300,7 @@ paths: responses: 200: description: |- - A SMS message has been sent to the specified phone number. Note + An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: @@ -501,7 +501,7 @@ paths: required: ['id_server'] responses: 200: - description: A SMS message was sent to the given phone number. + description: An SMS message was sent to the given phone number. schema: $ref: "definitions/sid.yaml" 403: From ab0c1bc054247f732e66dd2b424d8c3a12a5e492 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 08:41:35 +0100 Subject: [PATCH 11/21] Add changelog, update imperative check, rename sid.yaml --- api/client-server/administrative_contact.yaml | 14 +++++---- .../{sid.yaml => request_token_response.yaml} | 0 api/client-server/registration.yaml | 30 +++++++++---------- .../client_server/newsfragments/2101.breaking | 1 + 4 files changed, 25 insertions(+), 20 deletions(-) rename api/client-server/definitions/{sid.yaml => request_token_response.yaml} (100%) create mode 100644 changelogs/client_server/newsfragments/2101.breaking diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 4c1ea2e7..4438b643 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -135,7 +135,7 @@ paths: description: The addition was successful. examples: application/json: { - "submit_url": "https://example.org/path/to/submitToken" + "submit_url": "https://example.org/path/to/submitToken" } schema: type: object @@ -235,7 +235,9 @@ paths: the |/register/email/requestToken|_ endpoint. The homeserver has the choice of validating the email address itself, or proxying the request to the ``/validate/email/requestToken`` Identity Service API as - identified by ``id_server``. + identified by ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. operationId: requestTokenTo3PIDEmail parameters: - in: body @@ -260,7 +262,7 @@ paths: email containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -294,7 +296,9 @@ paths: the |/register/msisdn/requestToken|_ endpoint. The homeserver has the choice of validating the phone number itself, or proxying the request to the ``/validate/msisdn/requestToken`` Identity Service API as - identified by ``id_server``. + identified by ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. operationId: requestTokenTo3PIDMSISDN parameters: - in: body @@ -316,7 +320,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/api/client-server/definitions/sid.yaml b/api/client-server/definitions/request_token_response.yaml similarity index 100% rename from api/client-server/definitions/sid.yaml rename to api/client-server/definitions/request_token_response.yaml diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 00334434..5ec657e0 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -241,7 +241,7 @@ paths: may be an email containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -304,7 +304,7 @@ paths: that this may be an SMS message containing the validation token or it may be informing the user of an error. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: The homeserver does not permit the address to be bound. schema: @@ -402,11 +402,11 @@ paths: ``M_THREEPID_IN_USE`` may not be returned. The homeserver has the choice of validating the email address itself, - or proxying the request to the ``/validate/email/requestToken`` Identity - Server API. The request should be proxied to the domain that is sent by - the client in the ``id_server``. It is imperative that the homeserver - keep a list of trusted Identity Servers and only proxies to those it - trusts. + or proxying the request to the ``/validate/email/requestToken`` + Identity Service API. The request should be proxied to the domain that + is sent by the client in the ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` @@ -433,7 +433,7 @@ paths: 200: description: An email was sent to the given address. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a @@ -472,12 +472,12 @@ paths: to the given phone number prompting the user to create an account. ``M_THREEPID_IN_USE`` may not be returned. - The homeserver has the choice of validating the phone number itself, - or proxying the request to the ``/validate/msisdn/requestToken`` Identity - Server API. The request should be proxied to the domain that is sent by - the client in the ``id_server``. It is imperative that the homeserver - keep a list of trusted Identity Servers and only proxies to those it - trusts. + The homeserver has the choice of validating the phone number itself, or + proxying the request to the ``/validate/msisdn/requestToken`` Identity + Service API. The request should be proxied to the domain that is sent + by the client in the ``id_server``. It is imperative that the + homeserver keep a list of trusted Identity Servers and only proxies to + those that it trusts. .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken`` @@ -503,7 +503,7 @@ paths: 200: description: An SMS message was sent to the given phone number. schema: - $ref: "definitions/sid.yaml" + $ref: "definitions/request_token_response.yaml" 403: description: |- The homeserver does not allow the third party identifier as a diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking new file mode 100644 index 00000000..84c645ab --- /dev/null +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -0,0 +1 @@ +Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. From 0f82056ca2a46bd35483ee83c18c75035d85056f Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 08:43:34 +0100 Subject: [PATCH 12/21] Highlight breaking change --- changelogs/client_server/newsfragments/2101.breaking | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking index 84c645ab..bcbdcd55 100644 --- a/changelogs/client_server/newsfragments/2101.breaking +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -1 +1 @@ -Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. +Breaking change: Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. Clients should request a token from the user to submit 3PID validation when they received this field. Older clients will not know about this field and thus may display a deceptive message thinking that validation will be handled out of bounds. From d1fde0837af4ecfde83532f0c027bde4f4c5ea10 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:06:13 +0100 Subject: [PATCH 13/21] Consolidate id_server into ref. id_server/next_link are ignored --- api/client-server/administrative_contact.yaml | 24 ++----------------- .../definitions/request_email_validation.yaml | 14 ++++++++--- .../request_msisdn_validation.yaml | 14 ++++++++--- 3 files changed, 24 insertions(+), 28 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 4438b643..6ee4a152 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -244,17 +244,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: |- @@ -305,17 +295,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: An SMS message was sent to the given phone number. diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 5f15bd41..b99fe121 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -45,7 +45,15 @@ properties: next_link: type: string description: |- - Optional. When the validation is completed, the identity - server will redirect the user to this URL. + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. example: "https://example.org/congratulations.html" -required: ["client_secret", "email", "send_attempt"] + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" +required: ["client_secret", "email", "send_attempt", "id_server"] diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index 1a8c0cf8..08dd0482 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -51,7 +51,15 @@ properties: next_link: type: string description: |- - Optional. When the validation is completed, the identity - server will redirect the user to this URL. + Optional. When the validation is completed, the identity server will + redirect the user to this URL. This option is ignored when submitting + 3PID validation information through a POST request. example: "https://example.org/congratulations.html" -required: ["client_secret", "country", "phone_number", "send_attempt"] + id_server: + type: string + description: |- + The hostname of the identity server to communicate with. May optionally + include a port. This parameter is ignored when the homeserver handles + 3PID verification. + example: "id.example.com" +required: ["client_secret", "country", "phone_number", "send_attempt", "id_server"] From 7116f9334e8925e2c710c529dd1d0ab8c44209de Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:09:26 +0100 Subject: [PATCH 14/21] More consolidation --- api/client-server/registration.yaml | 48 +++-------------------------- 1 file changed, 4 insertions(+), 44 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 5ec657e0..edc52c6a 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -223,17 +223,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: |- @@ -286,17 +276,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: |- @@ -418,17 +398,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_email_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_email_validation.yaml" responses: 200: description: An email was sent to the given address. @@ -488,17 +458,7 @@ paths: name: body required: true schema: - allOf: - - $ref: "../identity/definitions/request_msisdn_validation.yaml" - - type: object - properties: - id_server: - type: string - description: |- - The hostname of the identity server to communicate with. May - optionally include a port. - example: "id.example.com" - required: ['id_server'] + $ref: "../identity/definitions/request_msisdn_validation.yaml" responses: 200: description: An SMS message was sent to the given phone number. From 2068cba598b3e3630950f95d0d730a1a2e081a56 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 09:14:25 +0100 Subject: [PATCH 15/21] Clients should submit a POST request --- api/client-server/administrative_contact.yaml | 8 ++++---- .../definitions/request_token_response.yaml | 16 +++++++--------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 6ee4a152..a3a391bc 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -145,10 +145,10 @@ paths: description: |- An optional field containing a URL where the client must submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. + to the Identity Service API's ``POST + /validate/email/submitToken`` endpoint. The homeserver must + send this token to the user (if applicable), which should + then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement. diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 50b45ca9..48f818e5 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -24,15 +24,13 @@ properties: submit_url: type: string description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's - ``/validate/email/submitToken`` endpoint. The homeserver - must send this token to the user (if applicable), which - should then be prompted to provide it to the client. + An optional field containing a URL where the client must submit the + validation token to, with identical parameters to the Identity Service + API's ``POST /validate/email/submitToken`` endpoint. The homeserver must + send this token to the user (if applicable), which should then be + prompted to provide it to the client. - If this field is not present, the client can assume that - verification will happen without the client's - involvement. + If this field is not present, the client can assume that verification + will happen without the client's involvement. example: "https://example.org/path/to/submitToken" required: ['sid'] From 572d29348c293012a03326c9ee0bfac74b76bf98 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Tue, 11 Jun 2019 00:18:37 +0100 Subject: [PATCH 16/21] Update changelogs/client_server/newsfragments/2101.breaking Co-Authored-By: Travis Ralston --- changelogs/client_server/newsfragments/2101.breaking | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2101.breaking b/changelogs/client_server/newsfragments/2101.breaking index bcbdcd55..68971171 100644 --- a/changelogs/client_server/newsfragments/2101.breaking +++ b/changelogs/client_server/newsfragments/2101.breaking @@ -1 +1 @@ -Breaking change: Add a new ``submit_url`` field to the response of various `.../requestToken` endpoints. Clients should request a token from the user to submit 3PID validation when they received this field. Older clients will not know about this field and thus may display a deceptive message thinking that validation will be handled out of bounds. +Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. From 1a22508e150071a275c08e3a13ace15211924f74 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 19:18:58 -0400 Subject: [PATCH 17/21] identity server -> the server --- api/client-server/definitions/request_token_response.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 48f818e5..8776d143 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -16,10 +16,9 @@ properties: sid: type: string description: |- - The session ID. Session IDs are opaque strings generated by the identity - server. They must consist entirely of the characters - ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they - must not be empty. + The session ID. Session IDs are opaque strings generated by a server. + They must consist entirely of the characters ``[0-9a-zA-Z.=_-]``. Their + length must not exceed 255 characters and they must not be empty. example: "123abc" submit_url: type: string From 5f24f63338f94a08c51754877a708fb596154e09 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 10 Jun 2019 19:21:14 -0400 Subject: [PATCH 18/21] Better wording --- api/client-server/definitions/request_token_response.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 8776d143..98fefe07 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -16,9 +16,9 @@ properties: sid: type: string description: |- - The session ID. Session IDs are opaque strings generated by a server. - They must consist entirely of the characters ``[0-9a-zA-Z.=_-]``. Their - length must not exceed 255 characters and they must not be empty. + The session ID. Session IDs are opaque strings that must consist entirely + of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 + characters and they must not be empty. example: "123abc" submit_url: type: string From ca8b539b2fe51e01c6042519aa04aa78b7e55d72 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 08:47:25 -0600 Subject: [PATCH 19/21] humans prefer to be treated as people --- api/client-server/administrative_contact.yaml | 2 +- api/client-server/definitions/request_token_response.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index a3a391bc..af7cdcd6 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -147,7 +147,7 @@ paths: submit the validation token to, with identical parameters to the Identity Service API's ``POST /validate/email/submitToken`` endpoint. The homeserver must - send this token to the user (if applicable), which should + send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index 98fefe07..bca57227 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -26,7 +26,7 @@ properties: An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's ``POST /validate/email/submitToken`` endpoint. The homeserver must - send this token to the user (if applicable), which should then be + send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification From b32f0e768f3a478e01913c997f97b5522b2baad5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 08:47:40 -0600 Subject: [PATCH 20/21] clarify that UIA can now be done by the HS --- specification/client_server_api.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 2e979cf7..fd63339e 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -762,17 +762,17 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once the OAuth flow has completed, the client retries the request with the session only, as above. -Email-based (identity server) -<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +Email-based (identity / homeserver) +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.email.identity`` :Description: Authentication is supported by authorising an email address with an identity - server. + server, or homeserver if supported. Prior to submitting this, the client should authenticate with an identity -server. After authenticating, the session information should be submitted to -the homeserver. +server (or homeserver). After authenticating, the session information should +be submitted to the homeserver. To use this authentication type, clients should submit an auth dict as follows: @@ -790,17 +790,17 @@ To use this authentication type, clients should submit an auth dict as follows: "session": "" } -Phone number/MSISDN-based (identity server) -<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +Phone number/MSISDN-based (identity / homeserver) +<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< :Type: ``m.login.msisdn`` :Description: Authentication is supported by authorising a phone number with an identity - server. + server, or homeserver if supported. Prior to submitting this, the client should authenticate with an identity -server. After authenticating, the session information should be submitted to -the homeserver. +server (or homeserver). After authenticating, the session information should +be submitted to the homeserver. To use this authentication type, clients should submit an auth dict as follows: From 56745c76aa24c3d358574540b0f011aff6f0b15f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 11 Jun 2019 09:22:02 -0600 Subject: [PATCH 21/21] Clarify that submit_url being not present only matters for r0.5 --- api/client-server/administrative_contact.yaml | 4 +++- api/client-server/definitions/request_token_response.yaml | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index af7cdcd6..c196c109 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -151,7 +151,9 @@ paths: then be prompted to provide it to the client. If this field is not present, the client can assume that - verification will happen without the client's involvement. + verification will happen without the client's involvement + provided the homeserver advertises this specification version + in the ``/versions`` response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" 403: description: The credentials could not be verified with the identity server. diff --git a/api/client-server/definitions/request_token_response.yaml b/api/client-server/definitions/request_token_response.yaml index bca57227..e47db8a0 100644 --- a/api/client-server/definitions/request_token_response.yaml +++ b/api/client-server/definitions/request_token_response.yaml @@ -30,6 +30,8 @@ properties: prompted to provide it to the client. If this field is not present, the client can assume that verification - will happen without the client's involvement. + will happen without the client's involvement provided the homeserver + advertises this specification version in the ``/versions`` response + (ie: r0.5.0). example: "https://example.org/path/to/submitToken" required: ['sid']