View source for Setting Up Single Sign-On for the Web Client

{{Template:Basic Cover
|title=Setting Up Single Sign-On for the Web Client
|type=FAQ
|htl=Y
}}

{{Template:Basic Status
|status=Published
|version=1.3
|authors=HTL QA
|applicableto=Supportworks ESP Version 7.5.0 and later, Web Client Version 1.1.0 and later
}}

== Setting Up Single Sign-On for the Web Client ==

It is possible to set up a Web Client single-sign-on   mechanism that will allow analysts in one or more domains of an   organisation to access the Web Client without having to explicitly  enter  their login credentials. Instead of displaying the login page at  the Web Client URL, the system authenticates transparently against the   user's Windows network credentials and takes the user directly to the  Web Client home page.

'''''Note:''''' It is assumed that each analyst who uses the Web Client and requires single sign-on has either the Active Directory or NT means of Windows authentication specified in their Supportworks analyst record. Other authentication options are not supported for single sign-on.

The key to single-sign-on capability is the Apache Web Server's SSPI module. This allows a Web-based   application to authenticate using any of the authentication protocols   built into the Windows Security Support Provider Interface.

The procedure for setting up single sign-on for the Web Client comprises a series of checks and adjustments performed in three separate areas of the system:

* Web server configuration
* One of the Web Client PHP files
* Main server configuration

In addition, it is worthwhile checking that certain local-intranet security options are set on any Web browsers that are expected to connect to the Web Client.

These sets of checks and adjustments are detailed in the following sections.

=== Checks/Adjustments to Perform in the Web Server Configuration ===

Carry out the actions relating to Web server configuration as follows:

# Open the text file ...\Hornbill\Core Services\SwHttpServer\conf\httpd.conf for editing.
# Near the top of the file (in Section 1), make sure the following values are set (normally, only <code>KeepAliveTimeout</code> will need to be changed - from 15 to 1 - due to a minor issue with Internet Explorer):
#::<code>Timeout 300</code>
#::<code>KeepAlive On</code>
#::<code>MaxKeepAliveRequests 100</code>
#::<code>KeepAliveTimeout 1</code>
# Search for the text <code>mod_auth_sspi.so</code>, which should appear within a <code>LoadModule</code> statement. You may find that this is commented out, so ensure that the line reads simply as follows:
#::<code>LoadModule sspi_auth_module modules/mod_auth_sspi.so</code>
# In Section 3 of the file, within each Virtual Host block being used for the Web Client, add a Directory directive resembling the following after the listed <code>Alias</code> statements:
#::<tt><Directory "C:\Program Files\Hornbill\Supportworks Server\html\webclient\sspi"></tt>
#::<code>    AllowOverride None</code>
#::<code>    AuthType SSPI</code>
#::<code>    AuthName "''Company-name''"</code>
#::<code>    SSPIAuth On</code>
#::<code>    SSPIAuthoritative On</code>
#::<code>    SSPIPerRequestAuth On</code>
#::<code>    SSPIOfferBasic On</code>
#::<code>    SSPIDomain ''DOMAIN-NAME''</code>
#::<code>    require valid-user</code>
#::<tt></Directory></tt>
#:Note   that you must use the directory path that applies to your Supportworks   installation, the company name that applies in your case, and the  network domain where the analysts' Windows accounts reside. The domain  name should just be that of the lowest-level domain. For multiple-domain   support, your network administrator must ensure that the domains   concerned have trust relationships with the domain you specify here.
# Save the httpd.conf file.
# Restart the Web server (SwHttpServer).
<!--
You   will recall that, in step 2 above, we changed the KeepAliveTimeout to  1  second. The following section in httpd.conf actually deals with keep-alives themselves and you could possibly edit this as necessary for all browsers:

:<code>BrowserMatch "Mozilla/2" nokeepalive</code>
:<code>BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0</code>
:<code>BrowserMatch "RealPlayer 4\.0" force-response-1.0</code>
:<code>BrowserMatch "Java/1\.0" force-response-1.0</code>
:<code>BrowserMatch "JDK/1\.0" force-response-1.0</code>-->

=== Checks/Adjustments to Perform in the Relevant Web Client PHP File ===

Here is the procedure to carry out on the Web Client module itself (within the Supportworks server):

# Open the text file ...\Hornbill\Supportworks Server\html\webclient\php\_wcconfig.php and uncomment the following line:
#::<code>define("_WC_TRUSTEDLOGON","TRUE");</code>
#  If your Windows network is set up to use Active Directory for  authentication and the User Principle Name (UPN - which may contain spaces and other characters not allowed in analyst IDs) is not identical to the corresponding analyst ID, then uncomment the following lines as well:
#::<code>define("_WC_UPN_SUPPORT","TRUE");</code>
#::<code>define("_WC_TOPLEVEL_DOMAIN","''top-level-domain-name''");</code>
#::(where <code>''top-level-domain-name''</code> comprises the last two components of the domain name - for example, <code>hornbill.com</code>)
#::Also, in this case, you must ensure that the Active Directory means of authentication and the relevant fully qualified User Principle Name (UPN) are specified in each of the Supportworks analyst records.
# Save the _wcconfig.php file.

=== Adjustments to Perform in the Main Server Configuration ===

To allow trust checking to occur between the Supportworks main server and the Web server, you have to configure the main server for "trusted authentication". Instructions are given in the chapter of the Supportworks ESP Configuration Guide entitled ''Configuring the Server for Trusted Authentication''.

Analysts in the relevant domains should now be able to access the Web  Client   transparently. However, a lot depends on your environment,  security settings and so on, so the above as given may not necessarily  work. If analysts are having problems, you should at least check the  browser-based settings indicated in the following section.

=== Checks to Perform in a Web Browser's Internet Options ===

The   Internet options you will be checking here would normally have been  set  as defaults in your domain policy. Follow these instructions on an   individual Web browser:

# Select Tools > Internet Options and click the Security tab.
# Select the "Local intranet" zone.
# Click the Sites button, followed by Advanced.
#   In the list of websites, ensure that you can see the DNS name or IP   address of the Supportworks Web server. If not, then add it to the zone.
# Click Close and then OK.
# With "Local intranet" still selected, click the "Custom level" button.
# Scroll down to the User Authentication > Logon section.
# Ensure that "Automatic logon only in Intranet zone" is selected.
# Click OK and then OK again.
# Restart the Web browser.

If there are still problems after this, please contact the Support Team for assistance.