Setting Up Single Sign-On for SelfService

Status:	Published
Version:	1.0
Authors:	HTL QA
Applies to:	Supportworks ESP Version 7.x

Setting Up Single Sign-On for SelfService

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

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 SelfService comprises a series of checks and adjustments performed in three separate areas of the system:

• Supportworks customer records
• Web server configuration
• SelfService PHP files

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

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

Checks/Adjustments to Perform in Supportworks Customer Records

In the record of each customer who is intended to have access to SelfService:

1. Ensure that the customer ID here matches the name used by that customer to log into their Windows domain. This could, for example, be their Active Directory name.
2. Change the customer's SelfService password to "_SSPI_DOMAIN", where DOMAIN (entered in capitals) is the name of the customer's domain.

Checks/Adjustments to Perform in the Web Server Configuration

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

1. Open the text file ...\Hornbill\Core Services\SwHttpServer\conf\httpd.conf for editing.
2. Near the top of the file (in Section 1), make sure the following values are set (normally, only KeepAliveTimeout will need to be changed - from 15 to 1 - due to a minor issue with Internet Explorer):

   Timeout 300

   KeepAlive On

   MaxKeepAliveRequests 100

   KeepAliveTimeout 1

3. Search for the text mod_auth_sspi.so, which should appear within a LoadModule statement. You may find that this is commented out, so ensure that the line reads simply as follows:

   LoadModule sspi_auth_module modules/mod_auth_sspi.so

4. Near the bottom of the file (in Section 3), after the Alias statements listed for each Virtual Host, add a Directory directive relating to SelfService, which should resemble the following:

   <Directory "C:\Program Files\Hornbill\Supportworks Server\html\_selfservice\SelfService-instance\sspi">

   AllowOverride None

   AuthType SSPI

   AuthName "Company-name"

   SSPIAuth On

   SSPIAuthoritative On

   SSPIPerRequestAuth On

   SSPIOfferBasic On

   SSPIDomain DOMAIN-NAME

   require valid-user

   </Directory>

   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 your users' 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.

5. Restart the Web server (SwHttpServer).

Checks/Adjustments to Perform in SelfService PHP Files

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

1. If the contents of the server variable $_SERVER['REMOTE_USER'] are constructed (by the SSPI module) in the format DOMAIN \ user, then in the text file ...\Hornbill\Supportworks Server\html\_selfservice\SelfService-instance\php\xmlhttp\customer_login.php, make sure the line beginning with $cred reads as follows:

   $cred = explode("\\",$_SERVER['REMOTE_USER']);

   Note that each backslash character within a string in PHP code always needs to be in duplicate.

2. Open the text file ...\Hornbill\Supportworks Server\html\_selfservice\SelfService-instance\index.php and search for the following line:

   var boolSkipLogin = false;

   Then change it to:

   var boolSkipLogin = true;

Users in the relevant domains should now be able to access SelfService transparently. However, a lot depends on your environment, security settings and so on, so the above as given may not necessarily work. If users 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:

1. Select Tools > Internet Options and click the Security tab.
2. Select the "Local intranet" zone.
3. Click the Sites button, followed by Advanced.
4. 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.
5. Click Close and then OK.
6. With "Local intranet" still selected, click the "Custom level" button.
7. Scroll down to the User Authentication > Logon section.
8. Ensure that "Automatic logon only in Intranet zone" is selected.
9. Click OK and then OK again.
10. Restart the Web browser.

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