.. _ext_auth:
=======================
External Authentication
=======================
.. contents::
:local:
:depth: 3
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 :ref:`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
.. code-block:: xml
https://example.com/ext_auth...
- 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).
.. code-block:: xml
1
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:
.. code-block:: none
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 :ref:`global-params` 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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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
+15551231234
+420800123456
johndow@some-special-hostname.com
myNetwork
.. 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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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:
.. code-block:: http
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"
}