Advanced

HTTP Interface

The 2019 version of the WhosOn Server has its own HTTP interface on port 8899. It will only respond to requests from hosts in the whitelist. Each request must also pass the Authentication String in the URL 'a={authstring}', e.g. http://localhost:8899/loadallsites.htm?a=AUTH

• index.htm (default) - the Server status page can be viewed via http://localhost:8899?a={authstring}. The status page shows server info, monitored sites and blacklisted clients.
• status.xml - returns the current server status as XML.
• status.json - returns the current server status as JSON.
• getgeoip.txt, getgeoip.xml, getgeoip.htm, getgeoip.json - returns GeoIP data for a given IP. Pass the ip address in the query string (eg: http://localhost:8899/getgeoip.xml?a=AUTH&ip=8.8.8.8)
• getlog.txt - returns the server log file for the current server session.
• chat.json - returns the JSON for a specific chat. Pass the Sitekey and ChatUID in the querystring (eg: http://localhost:8899/chat.json?a=AUTH&sitekey=1&chatuid=abcdefgh). The JSON returned is the same format that is used for the Cosmos Archiving.
• chat.htm - renders a chat using the chat template assigned to the site. Pass the Sitekey and ChatUID in the querystring.
• chat.xml, chat.txt - returns a chat as XML or text.
• site.xml, site.json - returns the XML or JSON site settings for the specified site. Pass the SiteKey in the querystring (eg: http://localhost:8899/site.json?a=AUTH&sitekey=1)
• loadsite.htm - forces a reload of the specified site. Pass the SiteKey in the querystring.
• loadallsites.htm - forces a reload of all sites.
• loaduser.htm - forces a reload of a specified user. Pass the username in the querystring (&username={username}).
• loadallusers.htm - forces a reload of all users.
• loadusergroups.htm - forces a reload of all user groups.
• loadworkperiods.htm - forces a reload of all work periods.
• loadskills.htm - forces a reload of all skills.
• loadsettings.htm - forces a reload of server settings.
• deletesite.htm - deletes a site. Pass the SiteKey in the querystring.
• deleteuser.htm - deletes a user.
• deleteusergroup.htm - deletes a user group. Pass the ID of the usergroup in the querystring (?id={id}).
• deleteworkperiod.htm - deletes a work period. Pass the ID of the work period in the querystring.
• user.json - returns JSON for a specified user. Pass the username in the querystring (&username={username}).
• users.json - returns a JSON array of users. Querystring params (all optional): &contains={text}&domain={domain}&status=[all,connected,0,1,2,3]&skills={skill,[skill]}.
• userphoto.json - returns a users photo as a JSON document. The photo is in base64 format.
• cannedresponses.json - returns a JSON document of all canned responses for a given user (&username={username}).
• pausesite.htm - pauses a site. Pass the SiteKey in the querystring.
• resumesite.htm - resumes a site. Pass the SiteKey in the querystring.
• chattingvisitors.json - returns a JSON list of all current chats.

Azure SSO

We are using OpenID Connect (OIDC) to support SSO. OIDC is an authentication layer that sits on top of OAUTH and is supported by many providers.

OIDC is currently only supported for Azure AD. Other providers may work, but they are not tested.

To use Azure SSO you must create an Azure AD Application, the steps are provided below.

Generating an authentication section in Azure

1. Go to Azure Active Directory.
2. Go to "App Registrations" on the left.
3. Click "New Registration".
4. Enter the name for the application. This will show up to users when they login if it is not pre-added to their user profile.
5. Choose what type of accounts you want to support. Most enterprises will select "accounts in this organizational directory only" however customers could select multi-tenant if they wanted to allow multiple servers or external accounts.
6. Click "Register".
7. Click "Certificates & secrets" on the left.
8. Click "New client secret".
9. Enter the description for example "WhosOn Server Secret".
10. Set the expiry date that is appropriate for you - note that if this secret expires, then authentication in WhosOn will stop working and a new secret will need to be generated.
11. Click "Add".
12. Copy the "Value" from the secret you have just created and replace this in the Template OIDC JSON below as {clientsecret}.
13. Click "Authentication".
14. Click "Add platform".
15. Select "Web".
16. Enter the first Redirect URI of "https://{server}/data/?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider" this must be HTTPS.
17. Check both boxes to allow "Access tokens" and "ID tokens".
18. Click Configure.
19. Click "Add URI" below the web section and add the following URIs:
    • https://{server}/settings/Login.aspx?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider
    • https://{server}/data/?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider
    • https://{server}/webclient/?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider
    • https://{server}/webclient/auth.html?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider
    • https://login.microsoftonline.com/common/oauth3/nativeclient?openid=Parkersoft.WhosOn.OpenId.MicrosoftOidcProvider
20. Click Save.
21. Click "Overview" on the left.
22. Copy the "Directory (tenant) ID" from the Essentials area and replace this in the Template OIDC JSON below as {tenantid}.
23. Copy the "Application (client) ID from the Essentials area and replace this in the Template OIDC JSON below as {clientid}.
24. Replace {customer-login-domain} with the main login domain for the Azure AD.

Template OIDC JSON

{ "IdDomain": "{customer-login-domain}", "IsEnabled": "true", "Name": "Azure AD", "Properties": { "TENANT": "{tenantid}", "CLIENTID": "{clientid}", "CLIENTSECRET": "{clientsecret}" } }

Adding SSO to the server

Use the Template OIDC JSON. Note that this JSON should be a single line for the registry to display it properly.

1. Access your WhosOn server.
2. Open regedit.
3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Parkersoft\WhosOn\7\Settings
4. Add a new string.
5. Name it: OpenIdConnectSettings
6. Paste the OIDC JSON into the string.
7. Restart WhosOn Server.
8. Restart IIS.

Using SSO

1. SSO will now be enabled for any email addresses that match the IdDomain.
2. Create a new user, and use the email address for the username. For existing users, the username OR email address should match with the username in the SSO system.
3. The password input field should disappear in the settings portal when adding / editing one of these users.
4. Save the user.
5. You should now be able to login correctly in the client, settings portal, data and web.
6. The login process always asks you your username the first time, and if you use a username that is in an OIDC directory, then you won't be asked for a password after clicking next.
7. If you check the "remember me" box then you won't be asked the username again unless you explicitly log out of the application.

Active Directory / LDAP Integration

This integration allows users to login with their LDAP or AD password to the WhosOn components.

Setting Up

1. Ensure that the windows server that WhosOn server is installed on is joined to the domain
2. Open up the service manager
3. Go to server settings
4. Go to advanced
   
5. Check the box to "Enable LDAP for User Logins"
6. Enter your LDAP Domain name (for example test.com)
7. Save the configuration

Creating Users

1. Open the settings portal
2. Create a new user as normal.
3. The username should be the same as the user's LDAP/AD username without any email address components
4. The password input box should be disabled.

Using the integration

1. Log in to WhosOn as normal, but input your LDAP or AD username or password.

Column level encryption

This guide describes how to configure column level encryption against your WhosOn database and have WhosOn function against this configuration.

SQL Server configuration

1. Install SSMS (SQL Server Management Studio) onto the WhosOn server.
2. Launch SQL Management Studio with "Run as administrator".
3. Log in to the correct database server with server admin details.
4. Right-click on the appropriate database.
5. After the right click go to Tasks -> Encrypt Columns.
   1. Column selection, set these options:
      • Userchatvars -> vardata. Encryption type = deterministic
      • VisitFormVars -> vardata. Encryption type = deterministic
      • UserChats -> MessageText. Encryption type = Randomized
      • UserChats -> VisitorName. Encryption type = deterministic
      • UserChats -> MessageEmail. Encryption type = deterministic
      • UserTranscript -> LineText. Encryption type = Randomized
   2. Next. Master Key Configuration
      • Auto Generate
      • Windows Certificate Store
      • Select a Master Key Source = Local Machine
   3. Next. Run Settings – Proceed to finish now
   4. Summary -> Finish
6. Open a New Query window and run the following SQL statements (replace <username> with the SQL user that your WhosOn server is using to connect to the database):

   SET ANSI_NULLS ON
     GO
     SET QUOTED_IDENTIFIER ON
     GO
     ALTER FUNCTION [dbo].[GetChatVars]
       (@SiteKey INT, @ChatUID CHAR (10))
       RETURNS NVARCHAR (MAX)
     AS
     BEGIN
       RETURN '';
     END
     
     ALTER FUNCTION [dbo].[GetChatTags]
       (@SiteKey INT, @ChatUID CHAR (10))
       RETURNS NVARCHAR (MAX)
     AS
     BEGIN
       RETURN '';
     END
     GO
     
     EXEC sp_refresh_parameter_encryption GetChatTags
     EXEC sp_refresh_parameter_encryption GetChatVars
     
     GRANT VIEW ANY COLUMN MASTER KEY DEFINITION TO <username>
     GRANT VIEW ANY COLUMN ENCRYPTION KEY DEFINITION TO <username>

   Copy

WhosOn server configuration

1. Open up MMC on your local machine.
2. Add in the Certificates Snap-In as Computer Account.
3. Expand out Certificates -> Personal -> Certificates.
4. Find and right-click on the "Always Encrypted Auto Certificate" and go to All Tasks -> Manage Private Keys...
   1. Click Add..., to add in a new user.
   2. Change the Locations... to the location machine (not the domain).
   3. Enter: IIS APPPOOL\WhosOnData as the object name and click Check Names. This should underline the user.
   4. Click OK and ensure that the new user has Full Control rights then click OK again.
5. Access the WhosOn registry location:
   HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ParkerSoft\WhosOn\7\Settings and edit the DBConnection and DBConnection.NET keys, replace the encrypted password with the plain text version.
6. Access the WhosOn registry location:
   HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ParkerSoft\WhosOn\7\Settings and edit the DBConnection and DBConnection.NET keys and add the following onto the end of the key (a single semi-colon should separate this from the rest of the key): Column Encryption Setting=enabled
   e.g. Provider=SQLNCLI11;Initial Catalog=dbname;Data Source=server;User ID=uid;Password=pwd;Column Encryption Setting=enabled
7. Restart the server.
8. Perform a Sanity Test and check the WO server log for any errors: migration

Chat Event Codes

If you want to review the chat data within the WhosOn database directly you will notice that the Events are coded into short descriptors, the below list is the glossary for those descriptors.