Authentication and Authorisation
Integrators using HTTP to communicate with Softdial Contact Center™ (SCC) must authenticate before being able to access the HTTP APIs provided by the various parts of SCC.
SCC has a simple model for authentication and authorisation, using Softdial Repository™ - an extensible configuration store that delivers APIs for authentication, query and publish-subscribe.
The HTTP Authentication API
The purpose of the authentication API is to ensure that communication with SCC services is made securely, but without over-complicating applications that make this communication.
The basic principle behind authentication is that anything that communicates with SCC does so either as a service (with full trust) or as an authenticated user, with a level of trust indicated by the user’s permissions.
The authentication API is used by SCC services to deliver federated authentication. For example, if using the Softdial HTTP proxy to communicate with CallGem, the session key returned from calling the auth method will be used by the proxy to check/ validate the permissions for that session. The same authenticated session can also be used to make HTTP requests into other services in the SCC ecosystem.
In SDMP terms, this is achieved using the User Authenticate [UA]/ User Status [US] message exchange.
The general dialog for any communication session is to first authenticate and then either cache the session key, or use the session cookie set in the response (named SCCOMNOMNOM) on future requests.
Authentication can be performed at landlord level or at a tenant level. The URL path that Repository listens on for auth requests is:
http://<WebServerHost>/softdial/repository/<tenant>/api/auth
Each tenant instance of Repository provides authentication for that tenant.
Authentication API Methods
Below is a description of the authentication methods, their parameters and expected responses. The documentation also describes use of the Sytel.Mdn2 class library for service implementors.
Sytel.Mdn2 is a utility class library for .NET applications, used by many SCC services, and is available to developers integrating with SCC.
Login
| Purpose |
|---|
| To authenticate and create an authorised session |
| Request types supported |
| GET POST * (See Parameters below) |
Parameters
| Parameter | Description |
|---|---|
| user | (Required) The name of a user that exists in the repository for a particular tenant |
| password | (Required) The user’s password |
* If using POST, the parameters must be put in the body of the post as a JSON frame e.g.
{"user":"Administrator","password":"a"}
Response
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | Returned when calling Login with a valid user & password, with a text/plain response containing the session id and Time to Live (TTL). The session id is also set into the standard session cookie. TTL is by default set to 30 minutes. Server-to-server sessions should check and re-authenticate on a timer. The default session TTL is configured in the SCCRepository.exe.config file under the appSettings key authCookieExpiryMinutes. |
| 500 | Returned when there is misconfiguration on the server, enclosing a text/plain response with a brief description of the error |
Example
http://localhost/softdial/repository/default/api/auth/Login?user=Administrator&password=a
yields a text/plain response:
FnBNUGcAXQ8XAR0MfiA0OC8mODEjNRlFJxYXLzAyN0pgUmRnd3hme2A.G0ktPUsmAEI2Mx4iACZ3Kmd6YnU8fCc0fiYsR0Qv
The response also sets the session cookie SCCOMNOMNOM, as shown in Fig. 1:
.NET implementation
using Sytel.Mdn.Web;
(bool) WebRoute.Authenticate(string pTenant, string pUser, string pPassword, out string pSessionID);
returns true or false depending on whether authentication succeeded. The session id is set using the out parameter pSessionID.
The form used for services:
using Sytel.Mdn.Web;
(bool) WebRoute.AuthenticateAsSystem(out string pSessionID);
returns true or false. The session id is set in pSessionID.
CheckPermissions
| Purpose |
|---|
| To validate credentials without creating a session, and return user configuration |
| Request types supported |
| GET |
Parameters
| Parameter | Description |
|---|---|
| user | (Required) The name of a user that exists in the repository for a particular tenant |
Response
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | Returned when calling CheckPermissions with a valid user, with an application/ json response containing the user configuration. This document is parsed by the Sytel.Mdn2 library Sytel.Mdn.Web.UserConfig class |
| 403 | All failures, to discourage brute force guess of tenant id. |
| 500 | May be returned in the event that there is misconfiguration on the server, enclosing a text/ plain response with a brief description of the error |
Example
http://localhost/softdial/repository/default/api/auth/CheckPermissions?user=Fred
For a success response, the returned JSON document contains user configuration including any configured agent endpoints:
{
"Permissions": 0,
"AgentDescription": "Tenant Admin",
"DefaultExtension": "",
"CurrFailedAttempts": 0,
"FromDatabase": false,
"LockedOut": false,
"webrtc": false,
"Name": "Fred",
"DataType": "User",
"Path": "default/Users/Administrator",
"Revision": 4,
"UUID": "79d27470-2c70-408f-bc41-6a5d35a24744"
}
.NET implementation
using Sytel.Mdn.Web;
(bool) WebRoute.CheckAuth(string pTenant, string pUser, string pPassword, out UserConfig pUserConfig);
returns true or false depending on whether authentication succeeded. The user config instance is set on successful authentication.
Validate
| Purpose |
|---|
| To validate a third party session id. A service will authenticate with SCC and will deliver its api to third parties (clients and other services). This is used by SCC services to provide federated authentication |
| Request types supported |
| GET POST |
Parameters
| Parameter | Description |
|---|---|
| session | (Required) The session id to test |
Response
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | Returned when calling validate with a valid session id, with a text/plain response containing the TTL for the third party session |
| 401 (Unauthorised) | Failure |
| 500 | May be returned in the event that there is misconfiguration on the server, enclosing a text/plain response with a brief description of the error |
Example
http://localhost/softdial/repository/api/auth/validate?session=JHACdikWShBZEBQeMBQ8IWkPMDAlPld3DiJ_W05FQEhkUGZjK30cOAYWLHseDWAENE0YOWcEFiMzLiUtYy05XC4daVsvFQsb
In this example, the session in the test parameter had been generated by another client.
The response is a text/plain message with the TTL expiry in ISO 8601 format:
2016-11-08T00:46:06Z
.NET implementation
using Sytel.Mdn.Web;
public class AuthCache
Each service that performs federated auth needs to create an instance of AuthCache once the service itself has authenticated.
Use of AuthCache in CallGemHTTPProxy is a reference implementation.
Logout
| Purpose |
|---|
| To end a communication session |
| Request types supported |
| GET POST |
Parameters
None
Response
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | Returned when calling Logout, with an empty response |
| 401 (Unauthorised) | Failure |
| 500 | May be returned in the event that there is misconfiguration on the server, enclosing a text/plain response with a brief description of the error |
Example
http://localhost/softdial/repository/api/auth/Logout
when called from a client that has cached the session cookie.
Yields an empty 200 (OK) response, and also removes the session cookie by setting TTL to the epoch time.
.NET implementation
None: service sessions auto expire.