External Authentication

Overview

For sharing contacts between mobile apps and WebRTC and also for Smart Contacts functionality, the apps need some way to validate that SIP username/password combination is valid and also find out which phone numbers are registered for this SIP account. This is what External Authentication service is for.

This web service must be implemented on provider side. The apps will call it and pass username&password combination together with Cloud ID of the app. The web service is expected to either return error in case the username/password combination is not valid, or return success and provide a list of phone numbers which are verified for this SIP account (using Phone Number Verifier)

Parameters

The parameters for this web service are fixed: username, host, password, cloud_id. They represent the SIP account username, password and CloudID of the app.

Configuration

The web service is configured via Cloud Softphone web portal “Provisioning Options” (Step 2).

External authentication URL

Contains the URL, including URL scheme, of the web service. Due to the purpose of this web service, only https: URLs will be accepted.

Example (with query-string):

https://example.com/ext_auth/?username=%username%&host=%host%&password=%password%&cloud_id=EXAMPLE1

Response

The response will be considered successful if the HTTP response code is 2xx. Any responses which have other response code, or whose body can’t be parsed, are silently ignored. Non-functional authentication web service will impair functionality of contact sync and smart contact resolution.

Content-type header of the response specifies the format of the body. The following Content-Types are supported:

  • application/xml (default)
  • application/json

In case of success, the web service should return list of all phone numbers verified for this SIP account. The response may also include the SIP uri where this user can be contacted. This parameter is optional - if it’s omitted, SIP account username (same as the input parameter) will be used. Second optional parameter is network_id - if it’s omitted, cloudId is used instead.

See the examples below for the response format.

Note

The phone numbers should be returned in E.164 format, with leading +

Example: +15551231234

Important

Normally, there will be just one phone number in the response - this will be the phone number which the user used and verified when creating account. There would be more numbers only in case when the provider wishes to link several phone numbers to the same SIP account.

See the examples below for the recognized formats of the responses.

Examples

GET method, XML

request:

GET /ext_auth/?username=johndow&host=sipdomain.com&password=12345678&cloud_id=EXAMPLE1 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-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/xml

<response>
    <phone-numbers>
        <phone-number>+15551231234</phone-number>
        <phone-number>+420800123456</phone-number>
    </phone-numbers>
    <uri>johndow@some-special-hostname.com</uri>
    <networkId>myNetwork</networkId>
</response>

Note

If someone has +15551231234 or +420800123456 number in address book and dials it with SmartContacts on, the app will make a call to johndow@some-special-hostname.com.

GET method, JSON

request:

GET /ext_auth/?username=johndow&host=sipdomain.com&password=12345678&cloud_id=EXAMPLE1 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-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/json

{
    "phoneNumbers" : [ "+15551231234", "+420800123456" ],
    "uri" : "johndow",
    "networkId" : "myNetwork"
}

Note

The uri here may be omitted - the app will use the SIP username by default.

POST method, JSON, failure

Note that the message in the response won’t be shown to user, it’s merely for debugging purposes.

request:

POST /ext_auth/ 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: 66

{"username" : "johnDow", "host" : "sipdomain.com", "password" : "invalid", "cloud_id" : "EXAMPLE1"}

response:

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

{
    "message" : "authentication failed"
}