Phone Number Verifier¶

Overview ¶

Cloud Softphone uses this web service to verify the phone number of user in case phone number sign-in is enabled. With phone number sign-in option, the app will show a registration wizard when it’s started after a fresh installation.

The first step of the wizard contains an input field where the user has to fill in his phone number. When submitted, the entered value is passed to this web service, which is expected to generate a secret PIN code and send it to this phone number via SMS.

The user must fill in the received PIN code into a field in the second wizard page. When submitted, the app will continue the provisioning process by invoking External Provisioning, passing the entered phone number as cloud_username and PIN code as cloud_password.

Note

Note that this wizard will be shown to both existing users and new users. It’s up to the external provisioning web service to check whether an account for the given phone number already exists and the web service can return existing credentials, or whether a new account should be created.

Parameters ¶

Since this web service is invoked before any accounts exist, only Global parameters can be used. There is also one specific parameter defined for this web service:

`phoneNumber`¶

The phone number entered by the user on the first wizard page. The number will be in international format, including country code, without any formatting. The number will always start with + sign.

Example: +15551231234 , +420800123456

Configuration ¶

The web service is configured via Cloud Softphone web portal, in white-label configuration step. This option becomes available when phone number sign-in is enabled in Features step.

`Phone number verifier url`¶

Contains the URL, including URL scheme, of the web service, possibly also with query string.

Example (with query-string):
https://example.com/verify_number/?number=%phoneNumber%&appid=%appid%&version=%version%
Example (without query-string, for POST):
https://example.com/verify_number/

`Phone number verifier post data`¶

If filled in, the app will use POST request verify phone number.

Example ( for application/x-www-form-urlencoded):
number=%phoneNumber%&appid=%appid%&version=%version%
Example ( for application/json ):
{ "number" : "%phoneNumber%", "appId": "%appid%" }

`Phone number verifier content type`¶

Specifies the value of Content-Type header to be sent in the request. If not specified, the app will default to application/x-www-form-urlencoded

Response ¶

The response will be considered successful if the response code is 2xx OK and the body is valid (or if there is no body). In this case, the app will switch to the second wizard page and the user can wait for the SMS to arrive.

In case of error, the response code should be non-2xx. The app will try to parse the body and extract “message” value from it. This message is then shown to the user in a message box. In case parsing fails, or no message is found, the app shows the first 100 characters of the raw response body.

In case the response code is 2xx OK and the body is not empty, it is parsed according to Content-Type and treated as a key->value map, where both keys and values are strings. The keys can be referenced in the extProv web service used in 2nd wizard step as %key% placeholders and the app will replace them with the corresponding values.

This can be used to further secure the registration wizard by generating a unique auth token together with the PIN code. The PIN code is sent via SMS, the token is stored on server and sent in the response back to the client. When the user fills in the PIN code from SMS in second wizard step, the client will send both the token and PIN code and the server can validate them. This makes “guessing” the right PIN code impossible without also knowing the token, which is transferred between the client and server over an encrypted connection.

Examples ¶

GET method (empty response)¶

request:

GET /verify/?phone=%2B15551231234&appid=com.cloudsoftphone.app HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

GET method (response with token)¶

request:

GET /verify/?phone=%2B15551231234&appid=com.cloudsoftphone.app HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

response:

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 123
Content-Type: application/json
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

{
    "authToken" : "d3a4613885ea53d5f230a42c91087f25fc3de87b"
}
Note

In case the app uses %authToken% in external provisioning web service definition, which is used to complete the second step of registration wizard, the value d3a4613885ea53d5f230a42c91087f25fc3de87b will be passed to server. The extProvPostData might look like this: u=%username%&p=%password%&t=%authToken%.

POST method, JSON ¶

request:

POST /verify/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
Content-Length: 183

{
    "phone"    : "+155",
    "appid"    : "com.cloudsoftphone.app"
}

response:

HTTP/1.1 400 Bad Bad
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Type: application/json
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

{
    "message"  :  "The number +155 is invalid."
}