Skip to content

Commit f5dc0ea

Browse files
uhoreguhoreg
authored
document msisdn-related endpoints in IS (#1507)
* add msisdn endpoints in Identity Server spec * add in CS endpoints that use the IS msisdn endpoints
1 parent 21dc6f8 commit f5dc0ea

File tree

5 files changed

+316
-8
lines changed

5 files changed

+316
-8
lines changed

‎api/client-server/administrative_contact.yaml

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ paths:
6666
medium:
6767
type: string
6868
description: The medium of the third party identifier.
69-
enum: ["email"]
69+
enum: ["email", "msisdn"]
7070
address:
7171
type: string
7272
description: The third party identifier address.
@@ -143,7 +143,21 @@ paths:
143143
validation tokens when adding an email address to an account. This API's
144144
parameters and response is identical to that of the HS API
145145
|/register/email/requestToken|_ endpoint.
146-
operationId: requestTokenTo3PID
146+
operationId: requestTokenTo3PIDEmail
147147
responses:
148148
200:
149-
description: An email was sent to the given address
149+
description: An email was sent to the given address.
150+
"/account/3pid/msisdn/requestToken":
151+
post:
152+
summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account.
153+
description: |-
154+
Proxies the identity server API ``validate/msisdn/requestToken``, but
155+
first checks that the given phone number is **not** already associated
156+
with an account on this Home Server. This API should be used to request
157+
validation tokens when adding a phone number to an account. This API's
158+
parameters and response is identical to that of the HS API
159+
|/register/msisdn/requestToken|_ endpoint.
160+
operationId: requestTokenTo3PIDMSISDN
161+
responses:
162+
200:
163+
description: An SMS message was sent to the given phone number.

‎api/client-server/registration.yaml

Lines changed: 90 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -196,11 +196,9 @@ paths:
196196
description: |-
197197
Proxies the identity server API ``validate/email/requestToken``, but
198198
first checks that the given email address is not already associated
199-
with an account on this Home Server. Note that, for consistency,
200-
this API takes JSON objects, though the Identity Server API takes
201-
``x-www-form-urlencoded`` parameters. See the Identity Server API for
199+
with an account on this Home Server. See the Identity Server API for
202200
further information.
203-
operationId: requestTokenToRegister
201+
operationId: requestTokenToRegisterEmail
204202
parameters:
205203
- in: body
206204
name: body
@@ -252,6 +250,71 @@ paths:
252250
}
253251
schema:
254252
"$ref": "definitions/errors/error.yaml"
253+
"/register/msisdn/requestToken":
254+
post:
255+
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
256+
description: |-
257+
Proxies the identity server API ``validate/msisdn/requestToken``, but
258+
first checks that the given phone number is not already associated
259+
with an account on this Home Server. See the Identity Server API for
260+
further information.
261+
operationId: requestTokenToRegisterMSISDN
262+
parameters:
263+
- in: body
264+
name: body
265+
schema:
266+
type: object
267+
properties:
268+
id_server:
269+
type: string
270+
description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
271+
example: "id.matrix.org"
272+
client_secret:
273+
type: string
274+
description: Client-generated secret string used to protect this session.
275+
example: "this_is_my_secret_string"
276+
country:
277+
type: string
278+
description: |-
279+
The two-letter uppercase ISO country code that the number in
280+
``phone_number`` should be parsed as if it were dialled from.
281+
phone_number:
282+
type: string
283+
description: The phone number.
284+
example: "[email protected]"
285+
send_attempt:
286+
type: number
287+
description: Used to distinguish protocol level retries from requests to re-send the SMS message.
288+
example: 1
289+
required: ["client_secret", "country", "phone_number", "send_attempt"]
290+
responses:
291+
200:
292+
description: |-
293+
An SMS message has been sent to the specified phone number.
294+
Note that this may be an SMS message containing the validation token or it may be informing
295+
the user of an error.
296+
examples:
297+
application/json: {}
298+
schema:
299+
type: object
300+
400:
301+
description: |-
302+
Part of the request was invalid. This may include one of the following error codes:
303+
304+
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
305+
However, if the home server has the ability to send SMS message, it is recommended that the server
306+
instead send an SMS message to the user with instructions on how to reset their password.
307+
This prevents malicious parties from being able to determine if a given phone number
308+
has an account on the Home Server in question.
309+
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
310+
that is not trusted by this Home Server.
311+
examples:
312+
application/json: {
313+
"errcode": "M_THREEPID_IN_USE",
314+
"error": "The specified address is already in use"
315+
}
316+
schema:
317+
"$ref": "definitions/errors/error.yaml"
255318
"/account/password":
256319
post:
257320
summary: "Changes a user's password."
@@ -319,10 +382,32 @@ paths:
319382
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
320383
321384
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
322-
operationId: requestTokenToResetPassword
385+
operationId: requestTokenToResetPasswordEmail
323386
responses:
324387
200:
325388
description: An email was sent to the given address
389+
"/account/password/msisdn/requestToken":
390+
post:
391+
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
392+
description: |-
393+
Proxies the identity server API ``validate/msisdn/requestToken``, but
394+
first checks that the given phone number **is** associated with an account
395+
on this Home Server. This API should be used to request
396+
validation tokens when authenticating for the
397+
`account/password` endpoint. This API's parameters and response are
398+
identical to that of the HS API |/register/msisdn/requestToken|_ except that
399+
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
400+
given email address could be found. The server may instead send an
401+
SMS message to the given address prompting the user to create an account.
402+
`M_THREEPID_IN_USE` may not be returned.
403+
404+
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
405+
406+
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
407+
operationId: requestTokenToResetPasswordMSISDN
408+
responses:
409+
200:
410+
description: An SMS message was sent to the given phone number.
326411
"/account/deactivate":
327412
post:
328413
summary: "Deactivate a user's account."

‎api/identity/phone_associations.yaml

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Copyright 2018 New Vector Ltd
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
swagger: '2.0'
15+
info:
16+
title: "Matrix Identity Service Phone Number Associations API"
17+
version: "1.0.0"
18+
host: localhost:8090
19+
schemes:
20+
- https
21+
- http
22+
basePath: /_matrix/identity/api/v1
23+
produces:
24+
- application/json
25+
paths:
26+
"/validate/msisdn/requestToken":
27+
post:
28+
summary: Request a token for validating a phone number.
29+
description: |-
30+
Create a session for validating a phone number.
31+
32+
The identity service will send an SMS message containing a token. If
33+
that token is presented to the identity service in the future, it
34+
indicates that that user was able to read the SMS for that phone
35+
number, and so we validate ownership of the phone number.
36+
37+
Note that Home Servers offer APIs that proxy this API, adding
38+
additional behaviour on top, for example,
39+
``/register/msisdn/requestToken`` is designed specifically for use when
40+
registering an account and therefore will inform the user if the phone
41+
number given is already registered on the server.
42+
43+
Note: for backwards compatibility with older versions of this
44+
specification, the parameters may also be specified as
45+
``application/x-form-www-urlencoded`` data. However, this usage is
46+
deprecated.
47+
operationId: msisdnRequestToken
48+
parameters:
49+
- in: body
50+
name: body
51+
schema:
52+
type: object
53+
example: {
54+
"client_secret": "monkeys_are_GREAT",
55+
"country": "GB",
56+
"phone_number": "07700900001",
57+
"send_attempt": 1
58+
}
59+
properties:
60+
client_secret:
61+
type: string
62+
description: A unique string used to identify the validation attempt.
63+
country:
64+
type: string
65+
description: |-
66+
The two-letter uppercase ISO country code that the number in
67+
``phone_number`` should be parsed as if it were dialled from.
68+
phone_number:
69+
type: string
70+
description: The phone number to validate.
71+
send_attempt:
72+
type: integer
73+
description: |-
74+
Optional. If specified, the server will only send an SMS if
75+
the ``send_attempt`` is a number greater than the most recent
76+
one which it has seen (or if it has never seen one), scoped
77+
to that ``country`` + ``phone_number`` + ``client_secret``
78+
triple. This is to avoid repeatedly sending the same SMS in
79+
the case of request retries between the POSTing user and the
80+
identity service. The client should increment this value if
81+
they desire a new SMS (e.g. a reminder) to be sent.
82+
next_link:
83+
type: string
84+
description: |-
85+
Optional. When the validation is completed, the identity
86+
service will redirect the user to this URL.
87+
required: ["client_secret", "country", "phone_number"]
88+
responses:
89+
200:
90+
description:
91+
Session created.
92+
examples:
93+
application/json: {
94+
"sid": "1234"
95+
}
96+
schema:
97+
type: object
98+
properties:
99+
sid:
100+
type: string
101+
description: The session ID.
102+
400:
103+
description: |
104+
An error ocurred. Some possible errors are:
105+
106+
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
107+
- ``M_SEND_ERROR``: The validation SMS could not be sent.
108+
"/validate/msisdn/submitToken":
109+
post:
110+
summary: Validate ownership of a phone number.
111+
description: |-
112+
Validate ownership of a phone number.
113+
114+
If the three parameters are consistent with a set generated by a
115+
``requestToken`` call, ownership of the phone number is considered to
116+
have been validated. This does not publish any information publicly, or
117+
associate the phone number address with any Matrix user
118+
ID. Specifically, calls to ``/lookup`` will not show a binding.
119+
120+
Note: for backwards compatibility with older versions of this
121+
specification, the parameters may also be specified as
122+
``application/x-form-www-urlencoded`` data. However, this usage is
123+
deprecated.
124+
operationId: msisdnSubmitTokenPost
125+
parameters:
126+
- in: body
127+
name: body
128+
schema:
129+
type: object
130+
example: {
131+
"sid": "1234",
132+
"client_secret": "monkeys_are_GREAT",
133+
"token": "atoken"
134+
}
135+
properties:
136+
sid:
137+
type: string
138+
description: The session ID, generated by the ``requestToken`` call.
139+
client_secret:
140+
type: string
141+
description: The client secret that was supplied to the ``requestToken`` call.
142+
token:
143+
type: string
144+
description: The token generated by the ``requestToken`` call and sent to the user.
145+
required: ["sid", "client_secret", "token"]
146+
responses:
147+
200:
148+
description:
149+
The success of the validation.
150+
examples:
151+
application/json: {
152+
"success": true
153+
}
154+
schema:
155+
type: object
156+
properties:
157+
success:
158+
type: boolean
159+
description: Whether the validation was successful or not.
160+
get:
161+
summary: Validate ownership of a phone number.
162+
description: |-
163+
Validate ownership of a phone number.
164+
165+
If the three parameters are consistent with a set generated by a
166+
``requestToken`` call, ownership of the phone number address is
167+
considered to have been validated. This does not publish any
168+
information publicly, or associate the phone number with any Matrix
169+
user ID. Specifically, calls to ``/lookup`` will not show a binding.
170+
171+
Note that, in contrast with the POST version, this endpoint will be
172+
used by end-users, and so the response should be human-readable.
173+
operationId: msisdnSubmitTokenGet
174+
parameters:
175+
- in: query
176+
type: string
177+
name: sid
178+
required: true
179+
description: The session ID, generated by the ``requestToken`` call.
180+
x-example: 1234
181+
- in: query
182+
type: string
183+
name: client_secret
184+
required: true
185+
description: The client secret that was supplied to the ``requestToken`` call.
186+
x-example: monkeys_are_GREAT
187+
- in: query
188+
type: string
189+
name: token
190+
required: true
191+
description: The token generated by the ``requestToken`` call and sent to the user.
192+
x-example: atoken
193+
responses:
194+
"200":
195+
description: Phone number is validated.
196+
"3xx":
197+
description: |-
198+
Phone number address is validated, and the ``next_link`` parameter
199+
was provided to the ``requestToken`` call. The user must be
200+
redirected to the URL provided by the ``next_link`` parameter.
201+
"4xx":
202+
description:
203+
Validation failed.

‎changelogs/client_server/newsfragments/1507.new

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
``POST /account/3pid/msisdn/requestToken``, ``POST /register/msisdn/requestToken``, and ``POST /account/password/msisdn/requestToken``

‎specification/identity_service_api.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,11 @@ Email associations
119119

120120
{{email_associations_is_http_api}}
121121

122+
Phone number associations
123+
~~~~~~~~~~~~~~~~~~~~~~~~~
124+
125+
{{phone_associations_is_http_api}}
126+
122127
General
123128
~~~~~~~
124129

0 commit comments

Comments
 (0)