/
number_verification.yaml
335 lines (316 loc) · 16.7 KB
/
number_verification.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
openapi: 3.0.3
info:
title: Number Verification
description: |
Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared.
It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token.
In this API **phone number** term refers to the mobile phone number
# Introduction
Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves.
It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned.
# Relevant Definitions and Concepts
- **Network-Based Authentication**: Authentication mechanism based on the identification of the endpoint of a network connection. Network operators know to which user a network resource is assigned at a given moment, for example the mobile phone number associated to a specific mobile network connection.
# API Functionality
This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service where the mobile device is accessing the *service provider* over a mobile network (WiFi connections are out of this API scope). This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves.
# Resources and Operations overview
This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (**excluding** for example by SMS/OTP or user/password as an authentication method):
- The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
- The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
# Sequence Diagram
Number Verification API uses the **standard [OAuth2 Authorization Code grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.1)**. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call.
**Additional details:**
- **(1):** Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in **[OIDC Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)**, ensures no user interaction.
- **(2):** The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver.
# Authorization and authentication
CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication.
# Further info and support
[GSMA Mobile Connect Verified MSISDN specification](https://www.gsma.com/identity/wp-content/uploads/2022/12/IDY.54-Mobile-Connect-Verified-MSISDN-Definition-and-Technical-Requirements-1.0.pdf) was used as source of input for this API. For more about Mobile Connect, please see [Mobile Connect website](https://mobileconnect.io/).
version: wip
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/number-verification/v0'
variables:
apiRoot:
default: http://localhost:9091
description: API root
tags:
- name: Phone number verify
description: API operation to verify a phone number received as input. It can be received either in plain text or hashed format.
- name: Phone number share
description: API operation to return the phone number associated to the access token.
paths:
/verify:
post:
tags:
- Phone number verify
summary: Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
description: |
Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided.
- The number verification will be done for the user that has authenticated via mobile network
- It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token
operationId: phoneNumberVerify
parameters:
- in: header
name: X-Correlator
required: false
description: Correlation id for the different services
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NumberVerificationRequestBody'
required: true
responses:
'200':
description: OK
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/NumberVerificationMatchResponse'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
'504':
$ref: '#/components/responses/Generic504'
security:
- openId:
- number-verification:verify
/device-phone-number:
get:
tags:
- Phone number share
summary: Returns the phone number associated with the access token
description: |
Returns the phone number so the API clients can verify the number themselves:
- It will be done for the user that has authenticated via mobile network
- It returns the authenticated user's `device phone number` associated to the access token
operationId: phoneNumberShare
parameters:
- in: header
name: X-Correlator
required: false
description: Correlation id for the different services
schema:
type: string
responses:
'200':
description: OK
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/NumberVerificationShareResponse'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
'504':
$ref: '#/components/responses/Generic504'
security:
- openId:
- number-verification:device-phone-number:read
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
schemas:
NumberVerificationRequestBody:
type: object
description: Payload to verify the phone number.
minProperties: 1
maxProperties: 1
properties:
phoneNumber:
type: string
pattern: '^\+[1-9][0-9]{4,14}$'
example: '+123456789'
description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
hashedPhoneNumber:
description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'.
type: string
example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
NumberVerificationMatchResponse:
type: object
description: Number verification result
required:
- devicePhoneNumberVerified
properties:
devicePhoneNumberVerified:
$ref: '#/components/schemas/DevicePhoneNumberVerified'
NumberVerificationShareResponse:
type: object
description: Number verification share result
required:
- devicePhoneNumber
properties:
devicePhoneNumber:
$ref: '#/components/schemas/DevicePhoneNumber'
DevicePhoneNumber:
type: string
pattern: '^\+[1-9][0-9]{4,14}$'
example: '+123456789'
description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
DevicePhoneNumberVerified:
description: Number verification. True, if it matches
type: boolean
ErrorInfo:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
description: HTTP response status code
code:
type: string
description: Code given to this error
message:
type: string
description: Detailed error description
responses:
Generic400:
description: Problem with the client request
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 400
code: INVALID_ARGUMENT
message: Client specified an invalid argument, request body or query param
Generic401:
description: Authentication problem with the client request
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 401
code: UNAUTHENTICATED
message: Request not authenticated due to missing, invalid, or expired credentials
PhoneNumberVerificationPermissionDenied403:
description: |
Client does not have sufficient permission.
In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
- Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
- Phone number cannot be deducted from access token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
PermissionDenied:
value:
status: 403
code: PERMISSION_DENIED
message: Client does not have sufficient permissions to perform this action
UserNotAuthenticatedByMobileNetwork:
value:
status: 403
code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
message: Client must authenticate via the mobile network to use this service
InvalidTokenContext:
value:
status: 403
code: NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
message: Phone number cannot be deducted from access token context
Generic500:
description: Server error
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 500
code: INTERNAL
message: Server error
Generic503:
description: Service unavailable. Typically the server is down.
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 503
code: UNAVAILABLE
message: Service unavailable
Generic504:
description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
headers:
X-Correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 504
code: TIMEOUT
message: Request timeout exceeded. Try later.
externalDocs:
description: Project documentation at CAMARA
url: https://github.com/camaraproject/NumberVerification