External Authentication¶

Overview ¶

The External Authentication service is called by SSO server and serves to validate user credentials based on authentication flow. If you use Contact Server, the External Authentication also serves for retrieving phone numbers registered for the SIP account.

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)

Authentication flows ¶

Simple flow ¶

In this case no external provisioning is defined and credentials provided by device are used for calling of external authentication service. These credentials are cloud username and cloud password and they are the same credentials that are used for sign in to the client application.

When registration wizard is involved or external provisioning is used then more advanced flows might be needed to use

External provisioning flow ¶

In many cases it is needed to use credentials that are provided by external provisioning in account.xml. The reason might be that it is sip username and sip password that needs to be used for authentication. Another reason might be that device is sending one time credentials from registration wizard.

When external provisioning is enabled then it is by default involved also in authentication flow (see below how to skip the external provisioning call). External authentication call is based on the data from account.xml and external authentication url template defined on the portal.

It is also possible to completely skip the external provisioning call.

Configuration ¶

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

External provisioning request ¶

The strategy of SSO to resolve the external provisioning URL resolution is following:

The highest priority has special xml tag that needs to be defined in Additional provisioning XML to be merged in section. The xml tag name is extSSOProvUrl. It needs to contain the same URL template as used in other provisioning URL sections. Together with the URL extSSOProvPostData and extSSOProvContentType might need to be used to define the web service request
<provisioning>
    <account>
        <core>
          <extSSOProvUrl>https://example.com/ext_auth...</extSSOProvUrl>
        </core>
    </account>
</provisioning>
If the highest priority url is not provided then URL for reprovisioning is used if provided

The lowest priority has initial provisioning url that is used only if those above are not provided

Skipping the external provisioning call when external provisioning is enabled can by done by adding a special xml tag that needs to be defined in Additional provisioning XML to be merged in section in portal configuration (Step 2).

<provisioning>
    <account>
        <core>
           <externalProvisioningOnSSODisabled>1</externalProvisioningOnSSODisabled>
        </core>
    </account>
</provisioning>

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.

It is possible to use following placeholders in the url to use credentials that are used for sign in on device side:

%username%

%password%

There is also legacy behavior of username, password placeholders to keep backwards compatibility for this flow. They are filled following way:

When username, password xml tags are found in external provisioning account.xml then their values are used for url composition on the position of mentioned placeholders.

When these values are not present then original credentials from device are used for the url composition

It is possible to use following placeholders in the url to use desired credentials from external provisioning:

%account[cloud_username]%

%account[cloud_password]%

%account[username]%

%account[password]%

Example of query strings:

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

https://example.com/ext_auth/?username=%account[cloud_username]%&password=%account[cloud_password]%&cloud_id=EXAMPLE1

Parameters ¶

It is possible to use also Global parameters in external authentication call templates

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 a list of all phone numbers verified for this SIP account. The phone numbers are used in the Contact Server to enable Smart Contacts functionality or identify user joining videoconference from PSTN. If you don’t use that, the phone numbers can be omitted from the response. 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

empty response with no body:

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

empty 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></response>

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

empty response with no body:

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

empty 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

{}

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"
}