Administration guide

This will serve as an administration guide for deployment and maintenace for the MindLink applications

Configuring External URLs for SSO

When using SSO, it is often convenient to redirect users to a custom page for login, or a custom page on logging out.

MindLink Anywhere allows this by configuring two keys in the ClientSettings.js JavaScript configuration file - found in the MindLink Anywhere client installation directory, or by editing two keys in the Connector Service's configuration file (MindLink.Core.Host.exe.config).

Setting a value for the ExternalLoginPageURL (ClientSettings.js) or gcwa.externalloginpageURL (ConnectorService configuration) key will redirect users to the specified URL when SSO fails.

Setting a value for the ExitPageURL (ClientSettings.js) or gcwa.exitpageURL (ConnectorService configuration) key will redirect users to the specified URL on logging out.

SSO using Windows Authentication

Kerberos operates using "principles" which are identifiers for users and services for which Kerberos tickets can be generated. So that a client can create a ticket readable by a service, it looks up the service principal name and asks the Kerberos server to produce a ticket that can be given to the service. Clearly if the service has no registered principal name, or an incorrect principal name is used (for instance falling back to a default service name) then the ticket will be incorrect and authentication will fail.

Windows authentication can be implemented by running the following command as a domain administrator:

Kerberos

Note this only affects Windows Authentication, NTLM does not use SPNs.

Version 3 of the MindLink Anywhere product supports a number of different authentication mechanisms. SSO can be enabled using either Windows and/or HTTP Header authentication. Within the management tool simply enable the 'Enable Windows Authentication' and/or 'Enable Pre-Authenticated HTTP Header Authentication'. See section 3 for more information. If one authentication mechanism fails to work successfully, it will failover to the next available authentication mechanism.

Enablingthe option 'Enable Password Authentication' simply presents a web version of the MindLink Anywhere username and password screen.

Note: as of 17.1 it is mandatory that you provide a token issuing certificate as this is used tomanage user authentication. To do so simply choose a relevant certificate from the 'Token Issuing Certificate:' section, ensuring that the certificate has a key length of 2048 bits and is setup for digital signing.

Also new for 17.1 it is possible to enable the user to select their preferred authentication mechanism. If more than one authentication mechanism is enabled it means that the user is able to differentiate between what mechanism they would prefer to use. For example, the user can either choose a) 'log me in with the best' or b) a specific mechanism. Also noteworthy is that once an authentication mechanism is chosen by the user, itwill be remembered in future instances.

Desktop Auth

Desktop Auth

External URL redirection

Desktop Auth

As of 17.1 it is possible to enable setup of external URL redirection. This can be setup in the event that authentication fails and/or when the user logs out. For example, if a user is unable to authenticate i.e. enters the wrong credentials it is possible to have them redirected to an external URL i.e. www.google.com. Likewise, the same is possible when the user logs out.

Scenario 1: Testing with an non-existent database

If you add a non-existent database in the connection string, you will be asked if you want to install one and populate it with the necessary MindLink schema and tables.

Scenario 2: Testing with an empty database

If the database you have directed MindLink to via the connection string, exists - but is empty - you will just be prompted to install the latest database schema and tables. In both cases, you will get a prompt to confirm the database installation. Finally, if the database connection string and the credentials are correct and/or the installation has been completed successfully, you will receive the following message: In case the database connection string is invalid (invalid format/ wrong database/ wrong server/ wrong credentials), you will receive an error screen with a full Exception dump of the error encountered.

Configuring the client

The application running ont he device has options to enable the server connection and user experience.

Server Settings for Application

For both iOS, the client is configured to connect to the Web Service URL.

For example, for a Web Service running on '7074' (as shown in the Web Service Port), the client should be configured as the following example shows:

http://{servername}:7074

If there is a proxy in front of the service, then the client should be configured with the proxy URL.

Secure Deployment

The following diagram shows the configuration necessary for a secure deployment. We make the following assumptions:

The Challenge Response Service and Host Identification Service listen on the same port.

Security on the File Transfer Service, Socket Service and MDS push communication is either globally enabled or disabled.

The same certificate is used to secure the Socket Service and the File Transfer Service.

MLM

Figure 18: Secure Deployment for Android

MLM

Figure 19: Secure Deployment for iPhone

The Management Tool is used to configure the socket service port, the port of the file transfer web service, and the shared port of the Challenge Response Service and Host Location Service.

By default, the Management Tool configures the socket service host name as the FQDN of the server. This value is customizable in the Management Tool if the organization has its network infrastructure setup, so that clients can make connections to a different address.

If security is enabled, the certificate used to secure the file transfer service and socket service must also be configured. The subject must be the host name of the broker service, and it must be issued by an authority trusted by the device.

  • The relative paths of each HTTP service are hardcoded constants.

  • The Host Location Service returns the details of the socket service and Challenge Response Service to the device.

File download links are sent in-band with the chat history as direct download links to the file transfer service. Hence, the client must only be configured with the load-balanced URL of the Host Identification Service.

HTTP Proxy

Given that the client connects to the proxy and not directly to the hostname, port or even potentially the relative path of the actual broker service when using an HTTP proxy, the actual URLs to connect to must be made configurable.

Since the client connects to the URL in its own IT policy or local configuration for the Host Location Service, only the URLs of the Challenge Response Service and the File Transfer Service must be configured on the server via the Management Tool/app config.

MLM

Figure 20: HTTP Proxy Configuration for iPhone

  • The Challenge Response Proxy URL and File Transfer Proxy URL are configured on the server via the Management Tool/app config.

  • The proxy URL of the Challenge Response Service is sent to the client in the response from the Host Location Service.

  • The File Transfer Proxy URL is used to form file download links sent to the client in messages.

Note: the security protocol on the proxied URLs is not necessarily linked to whether security is enabled on the server, as the HTTP proxy may be configured to perform HTTPS communication and/or offloading between itself and the client, or itself and the Mobile Broker.

The client is configured with the proxied URL of the load balanced Host Location Service.

Group Chat Disabled

As of 17.3 MindLink Mobile supports a Skype for Business/Lync topology that does not have PChat installed; this is achieved by enabling administrators and subsequently users to choose between modalities (if supported). Please note: this should be discussed during the planning phase.

Pre-requisites:

  • Service account with read/write permissions to the preferences repository

  • Preferences repository stored locally or on a network drive. Default location for Local Preferences Repository is \Program Files\MindLink Software\MindLink Mobile\Connector Service\preferences. This can be changed to any local or network file location within the 'Lync/Skype for Business' tab within the MindLink Managment Center.

MLM

Figure 24: SharePoint Feature Settings

1 - SharePoint API Port: The port on which to listen for incoming SharePoint server MTLS connections required only when configuring for Single Sign-On.

2 - Certificate: The server certificate to use for incoming SharePoint MTLS connections. This authenticates the Connector Service to the SharePoint server required only when configuring for Single Sign-On.

3 - Authorized Hosts: The authorized hosts collection should contain the FQDN of all SharePoint hosts that will connect to the Connector Service instance being configured required only when configuring for Single Sign-On.

If a SharePoint host attempts to connect to the Connector Service and is not in the Authorized Host collection, an error indicating that the host is not authorized will be returned.

Windows Authentication

Kerberos operates using principleswhich are identifiers for users and services for which Kerberos tickets can be generated. So that a client can create a ticket readable by a service, it looks up the service principal name and asks the Kerberos server to produce a ticket that can be given to the service. Clearly if the service has no registered principal name, or an incorrect principal name is used (for instance falling back to a default service name) then the ticket will be incorrect and authentication will fail.

Windows integrated authentication can be implemented by running the following command as a domain administrator:

MLM

Note this only affects Windows Authentication, NTLM does not use SPNs.

Single Sign-On

Single Sign-On allows a user to log onto related systems once and not have to re-enter their credentials for each system. Enabling SSO involves the configuring of the adaptor, and may involve extra configuration depending on the type of connector. For all connectors, the client must be told to connect via SSO by checking the Enable SSO box.

There are two protocols which support Single Sign-On, 1. Windows Authentication and 2. HTTP Header Authentication

Mechanisms

Windows Authentication

MindLink Anywhere Single Sign-On supports both Windows Integrated Authentication and NTLM mechanisms.

Windows Integrated Auth is supported browsers except Safari. If Kerberos is not available, Single Sign-On automatically resorts to NTLM.

For Kerberos to be supported, the MLA URL must be registered as a Service Principal Name.

HTTP Header Authentication

MindLink Anywhere Version 3 supports Windows authentication as detailed above. in addition, Version 3 also supports HTTP Header Authentication. Enabling this option allows HTTP headers to be passed to an external authentication module, for example a proxy server.

Example:User credentials can be read from the relevant attributes within the HTTP header of theuser's security certificate. These attributes are thenauthenticated against an authentication module such as a proxy. Once authenticated successfully, a session is thenestablished.

further information on SSO can be found in the Pre-Requisites section found further information on SSO can be found in the Pre-Requisites section found here

Creating Trusted Applications

Information on how to configure Trusted Applications cans be found in the Pre-Requisites section found here

Group Chat Client Add-Ins

Microsoft Group Chat supports Client Add-Ins. These are special panels that appear below the chat input panel in chat rooms. The system administrator configures which panel appears in which chat room using the Group Chat Administration Tool.

Client Add-Ins are actually web pages hosted inside the Group Chat Console client, which communicate with the parent window using JavaScript.

This table shows in which cases Proxy and Rules are needed according to whether the Add-In is old or new and which browser you are operating from.

MindLink Anywhere hosts each Client Add-In inside an Html IFRAME element within the MindLink Anywhere page. The Client Add-In can communicate with MindLink Anywhere using the same JavaScript calls as in the Group Chat Console client.

However, to enable this communication to happen, both MindLink Anywhere and the Client Add-In page must be served from the same domain and port address. This is a standard security requirement enforced by all browsers.

For instance, if MindLink Anywhere is served from http://www.MindLink.net/MindLink Anywhere, then for any Client Add-In to be shown in MindLink Anywhere it must also be served from a relative path on http://www.MindLink.net e.g. http://www.MindLink.net/myclientaddin.

In an enterprise environment, it is often not the case that MindLink Anywhere and any Client Add-Ins will be served from the same actual machine. Hence, they will be served from different domains/ports and so Client Add-In/MindLink Anywhere communication will be forbidden. The use of a reverse-proxy is therefore required to mux requests to MindLink Anywhere and to any configured Client Add-Ins to the same domain. This can be achieved by configuring the reverse-proxy with forwarding rules based on the relative-path of the incoming HTTP request. The reverse-proxy is not a component of MindLink Anywhere and must be sourced from a third-party vendor.

It may also be the case that a Client Add-In's URL as loaded by Group Chat Console clients is not that which is exposed by the MindLink Anywhere reverse-proxy. In this case, the Add-In should be configured using the Group Chat MindLink Management Center as the URL that the Group Chat Console should load. MindLink Anywhere should then be configured using the add-in re-write rules configuration key, to convert the Add-Ins URL into the URL that the reverse-proxy exposes it as.

The add-in re-write rules configuration setting is a set of key/value pairs. The "key" is a regular expression to test any Client Add-In URLs against. If the regex matches, the Client Add-In URL is transformed using the "value" string. The value string supports regex style group placeholders (e.g. $1) to re-use elements of the original matched URL.

For instance: to re-write an internal Client Add-In URL of:

  • http://addins.MindLink.net/ to the external address of http://MindLink Anywhere.MindLink.net/addins/

the regular expression would be http://addins.MindLink.net/(.*), and the replacement would be http://MindLink Anywhere.MindLink.net/addins/$1 In the MindLink Management Center, this would be typed in the add in re write rules config box as:

  • http://addins.MindLink.net/(.*), http://MindLink Anywhere.MindLink.net/addins/$1;

Note that the literal special characters in the regular expression "key" string are escaped with a backslash.

An example Client Add-In configuration is shown below.

MLM

Figure 113: Example proxy and MindLink Anywhere configuration

The enable an add-in, a check box can be used to disable Client Add-In support across the whole system in all chat rooms, if needed.

High Availability

Here we discuss high-availability strategies for each tier in the MindLink stack, in terms of node failure within a clustered pool.

The MindLink Server may be deployed in a pool configuration to support high availability. This mechanism ensures that there is always a MindLink Server available to service new log on requests.

The administrator should monitor the service health via the HTTP health check service, performance counters, and status of the Windows Service. The load balancer should be configured to maintain the candidate set of nodes by monitoring the HTTP health check service.

Scenario: A MindLink Server node becomes unavailable:

- Administrative actions:

    - Diagnose the fault and restart the service.
    - The load balancer will remove the node from the candidate node list and redirect new log on requests to the other available servers.
    - When the node recovers the load balancer will begin directing it new log on requests.


- Anywhere/SharePoint user experience:

        - The user will be notified that they have been disconnected from their session and reconnection will be attempted.
        - After failure to reconnect for longer than the configured session timeout interval, the user will be instructed to re-logon.
        - If the node is restarted within the session timeout interval, then the user will be instructed to re-logon immediately.


- Mobile user experience:

    - The user will be notified that they have become disconnected.
    - The app will continue to attempt to reconnect periodically.
    - The user may close and restart the app, at which point they will be given the choice to continue attempting reconnection or to re-logon to a different node.
    - When the node is restarted, the user will be immediately informed that their session ended and instructed to re-logon.

Skype for Business

MindLink integration is supported with all SfB highly available pool configurations and load balancing mechanisms.

Scenario: The account's home frontend server in an Enterprise pool becomes unavailable:

- Administrative actions:

    - None.
    - New log on requests will be handled by other available frontend nodes.


- Anywhere/SharePoint/Mobile user experience:

    - The user will be notified that their session has ended and instructed to re-log on.
    - On re-logging on, a SfB session will be established on another node in the frontend pool.


- API behaviour:

    - The agent and channels will become inactive.
    - The agent will attempt to automatically reconnect and eventually become active and re-activate its channels.

Scenario: A server in the Persistent Chat pool becomes unavailable:

- Administrative actions:
     - None.
     - New log on requests will be handled by other available frontend nodes.


- Anywhere/SharePoint/Mobile user experience:

- The user will be notified that their session has ended and instructed to re-log on.
- On re-logging on, a SfB session will be established on another node in the frontend pool.


- API behaviour:

- The agent and channels will become inactive.
- The agent will attempt to automatically reconnect and eventually become active and re-activate its channels.

Database Layer (Mobile)

MindLink supports SQL Server Mirroring, Clustering and Always-On Availability Groups for high-availability of the SQL database used for deployment of the mobile server in a pool.

Scenario: The database layer becomes unavailable for a single MindLink Server node.

- Administrative actions:

    - Repair the connection between the MindLink Server and the database.


- Failover process:

    - The MindLink Server periodically monitors the connectivity to and health of the database layer.
    - When a MindLink Server node identifies that it has not been able to connect to the database layer for a period of time, it will remove itself from the pool:

        - All active user sessions will be terminated.
        - All log on requests will be rejected.
        - The HTTP health check service will report the status as unavailable. The load balancer should then remove it from the candidate node set.


    - When the database layer recovers, the MindLink Server will observe this and begin accepting new log on requests.


- User experience:

    - Logged on users will have their session removed and will be informed that they need to re log on.
    - The load balancer will redirect the log on request to an available node and they will restart their session on that node.

Scenario: An SQL Server node becomes unavailable:

- Administrative actions:

    - None.
    - Database queries will be handled by other available database nodes.


- Failover process:

    - When a node fails, SQL operations may begin to fail and whilst the node is taken out of the cluster (or in the case of mirroring, the connection is failed over to the mirror database).
    - Recovery and reconnection to the healthy pool nodes is automatic and should not result in MindLink outage.


- User experience:

    - Logged-on users will not experience any outage.
    - Users attempting to log on as the SQL node fails may fail to log on while the node is taken out of the pool.
    - Once the failed node has been automatically taken out of the pool (depending on the HA mechanism), users will be able to log on.

MAM and MDM Deployment

Configuration and Deployment Information can be found here

Enabling Conversation History (SFB2015/SFB2019/SfBO)

For conversation history to be saved to the users Conversation History folder within Exchange the following minimum criteria need to be met.

  • Server Side Conversation History is supported by MS Exchange 2013 or above.

  • Server Side Conversation History is supported by Skype for Business 2015 server or above.

  • Server Side Conversation History is supported by Skype for Business Online.

  • MindLink Anywhere and MindLink Mobile version needs to be 17.1 or above.

  • Integration between Skype for Business 2015/Skype for Business 2019 and MS Exchange needs to be enabled buy creating a OAuth partnership between these applications. A guide to create this integration can be found here : https://technet.microsoft.com/en-us/library/jj688151.aspx?f=255&MSPPError=-2147217396

  • Server Side Conversation History needs to be enabled in your Skype for Business environment. Documentation to enable this setting can be found here: https://technet.microsoft.com/en-us/library/dn985897.aspx

Bibliography

  1. Microsoft. Enterprise Library Logging Application Block. Online http://msdn.microsoft.com/en-us/library/cc511708.aspx.

This content is licensed under the terms of the Terms of Service