Sentinel Web Service API

On-site Courses

Sentinel Web Service Whitepaper

Overview

The sentinel service validates the supplied security credentials from the Simplicity desktop application to assess whether the connection to the client database is permitted.

All parameters passed to this service and all responses from the service are encrypted multiple times to ensure security and validity.

The encrypted parameters that are passed to this service include;

  • Windows User Name – E.g. “Joe Bloggs”
  • Computer Name – E.g. “JoesPC”
  • Domain Name – E.g. “BLOGGSINC”
  • CodeSet – E.g. “27000”

The last character identifies the environment

  • Production: CodeSet will end with “0”
  • Test: CodeSet will end with “1”
  • Development: CodeSet will end with “2”

The leading characters identifies the implementation

Once valid credentials have been supplied the sentinel service provides the desktop application with the location, port and name of the client database to connect to.

The sentinel service requires access to the User Maintenance database to validate the supplied security credentials against. Credentials are setup via the “Simplicity User Maintenance” application. These are typically set to match on CodeSet, Domain Name and Windows User Name. This allows for a good balance of flexibility and security for the corporate environment. Please refer to the “User Maintenance Whitepaper” for further details in setting users up.

The service also provides the desktop application with the sql credentials to establish its connection to the client database. Sentinel uses accesses the user maintenance database to both validate the security credentials provided by the application and also to lookup the appropriate sql credentials for the application to use.

All passwords are stored encoded in the database. Decoding routines are not present in the database. In the event such routines are required to be present in the database then a formal request must be made in writing to Simplicity for these changes to be made.

The desktop application user will not be aware of what credentials (sql username and password) have been used to establish the database connection with. It is not advised that users ever be made aware of these usernames and passwords.

Simplicity sentinel web service is accessed via https on port 443 at the following primary url:

https://sentinel.simplicitycrm.com/sentinelsvc.asmxor sentinel via http on port 80 at the following primary url:

http://sentinel.simplicitycrm.com/sentinelsvc.asmx

Accessibility Diagrams

The web service is accessed via standard web requests from the Simplicity SLS server as illustrated.

SENTINEL SERVICE HOSTED AT SIMPLICITY

This model is the recommended setup for the Simplicity sentinel service.

SENTINEL SERVICE HOSTED BY CLIENT – INTRANET ACCESS ONLY

This model is available when the Simplicity licensing subscription purchased allows for in-house implementation of Simplicity.

SENTINEL SERVICE HOSTED BY CLIENT – INTRANET & INTERNET ACCESS

This model is available when the Simplicity licensing subscription purchased allows for in-house implementation of Simplicity. A NAT or routing entry will need to be created to allow access from the external world to the server. The access required will be for TCP traffic on Port 80 from the external world IP address of the clients to the internal IP address of the SLS server.

Web Service Method Definitions

The following methods are supported by this web service.

Web Service Method - GetAvailableDatabases

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Sentinel/GetAvailableDatabases"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetAvailableDatabases xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</GetAvailableDatabases>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetAvailableDatabasesResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetAvailableDatabasesResult>string</GetAvailableDatabasesResult>

</GetAvailableDatabasesResponse>

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetAvailableDatabases xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</GetAvailableDatabases>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetAvailableDatabasesResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetAvailableDatabasesResult>string</GetAvailableDatabasesResult>

</GetAvailableDatabasesResponse>

</soap12:Body>

</soap12:Envelope>

Web Service Method - GetAvailableDesktopInterfaces

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Sentinel/GetAvailableDesktopInterfaces"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetAvailableDesktopInterfaces xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</GetAvailableDesktopInterfaces>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetAvailableDesktopInterfacesResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetAvailableDesktopInterfacesResult>string</GetAvailableDesktopInterfacesResult>

</GetAvailableDesktopInterfacesResponse>

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetAvailableDesktopInterfaces xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</GetAvailableDesktopInterfaces>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetAvailableDesktopInterfacesResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetAvailableDesktopInterfacesResult>string</GetAvailableDesktopInterfacesResult>

</GetAvailableDesktopInterfacesResponse>

</soap12:Body>

</soap12:Envelope>

Web Service Method - GetSessionId

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Sentinel/GetSessionId"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetSessionId xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

</GetSessionId>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<GetSessionIdResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetSessionIdResult>string</GetSessionIdResult>

</GetSessionIdResponse>

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetSessionId xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

</GetSessionId>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<GetSessionIdResponse xmlns="http://services.simplicitycrm.com/Sentinel">

<GetSessionIdResult>string</GetSessionIdResult>

</GetSessionIdResponse>

</soap12:Body>

</soap12:Envelope>

Web Service Method - LogMessage

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://services.simplicitycrm.com/Sentinel/LogMessage"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<LogMessage xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</LogMessage>

</soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<LogMessageResponse xmlns="http://services.simplicitycrm.com/Sentinel" />

</soap:Body>

</soap:Envelope>

SOAP 1.2

POST /sentinelsvc.asmx HTTP/1.1

Host: sentinel.simplicitycrm.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<LogMessage xmlns="http://services.simplicitycrm.com/Sentinel">

<Key>string</Key>

<Data>string</Data>

</LogMessage>

</soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<LogMessageResponse xmlns="http://services.simplicitycrm.com/Sentinel" />

</soap12:Body>

</soap12:Envelope>

Web Service Setup & Configuration

Multiple configuration documents are present in the ~\APP_DATA\ web service folder. The returned results are the prioritisedsuperset of all the configuration documents matching the supplied ClientID and CodeSet. The result location ordering returned is based on the “Rank” attribute with the higher the number, the higher the priority.

WEB.CONFIG

The following is a sample of sentinel’s web.config file. The placeholders shown need to be replaced with actual values. ClientImplementationInstanceNumber shown below needs to be set “1” for the primary sentinel service, “2” for the first backup service, “3” for the second backup, etc.

<?xml version="1.0"?>

<configuration>

<configSections>

<section name="Sentinel" type="SAConfigSection.SAConfigSectionHandler,SAConfigSection"/>

</configSections>

<Sentinel>

<ClassName>Sentinel.SentinelConfiguration,Sentinel</ClassName>

<AccessKey>f69ab6e7-8d1a-41ab-a13d-2975d0a777ae</AccessKey>

<InstanceId>ClientImplementationInstanceNumber</InstanceId>

<Databases>

<ClassName>Sentinel.SentinelDatabaseCollection,Sentinel</ClassName>

<ItemClassName>Sentinel.SentinelDatabase,Sentinel</ItemClassName>

<Items>

<Item>

<ServerName>UserMaintenanceDbServerName</ServerName>

<Port>UserMaintenanceDbServerPort</Port>

<DatabaseName>UserMaintenanceDatabaseName</DatabaseName>

<UserName>UserMaintenanceDbUserName</UserName>

<Password>UserMaintenanceDbPassword</Password>

<ConnectionTimeoutInSeconds>10</ConnectionTimeoutInSeconds>

<ConnectionRetryCount>3</ConnectionRetryCount>

<ExecutionTimeoutInSeconds>10</ExecutionTimeoutInSeconds>

<ExecutionRetryCount>3</ExecutionRetryCount>

</Item>

</Items>

</Databases>

</Sentinel>

<appSettings/>

<connectionStrings/>

<system.web>

<compilation debug="true" strict="false" explicit="true" />

<pages>

<namespaces>

<clear />

<add namespace="System" />

<add namespace="System.Collections" />

<add namespace="System.Collections.Specialized" />

<add namespace="System.Configuration" />

<add namespace="System.Text" />

<add namespace="System.Text.RegularExpressions" />

<add namespace="System.Web" />

<add namespace="System.Web.Caching" />

<add namespace="System.Web.SessionState" />

<add namespace="System.Web.Security" />

<add namespace="System.Web.Profile" />

<add namespace="System.Web.UI" />

<add namespace="System.Web.UI.WebControls" />

<add namespace="System.Web.UI.WebControls.WebParts" />

<add namespace="System.Web.UI.HtmlControls" />

</namespaces>

</pages>

<authentication mode="Windows" />

</system.web>

</configuration>

Service Workflow

SENTINEL SERVICE PASSING VALID CREDENTIALS DATAFLOW

When valid credentials are supplied to the sentinel service connection information is passed back to the desktop application for it to then connect to the client’s database with.

This session code and successful connection are logged in the “User Maintenance” database for audit and support purposes.

SENTINEL SERVICE PASSING INVALID CREDENTIALS DATAFLOW

When invalid credentials are supplied to the sentinel service a reply is returned with a session code that is displayed by the desktop application.

Access to the client database is denied and no attempt is made to connect to it.

This session code can be looked up in the “User Maintenance” database for audit and support purposes.

SENTINEL SERVICE UNAVAILABILITY DATAFLOW

Should the sentinel service be temporarily or permanently unavailable the Simplicity desktop application will be unable to connect to the database.

When the sentinel service is being hosted by Simplicity then multiple redundancy services are provided.

For in house implementations either the sentinel service should reside on a web server that has a failover or multiple sentinel services should be setup on separate servers.

Australia - New Zealand
© - SimplicityCRM All Rights Reserved.