Single Sign On for HP OpenView ServiceDesk 4.5

version 1.8 [30th of September, 2013]

created by Radovan Skolnik, radovan@skolnik.info (comments and questions are welcome)

please, sign a Petition to Open Source HP OpenView ServiceDesk 4.5

1. Overview

1.1 Summary

This package provides Single Sign On functionality for both versions of the HP OpenView ServiceDesk 4.5 clients as well as WEB-API applications. This means that (you can use any or all of these in your environment)

The whole thing is created as add-on to original functionality - existing stuff (both server and client) still works the same as without this and is not affected in any way.

1.2 Download

You can download the whole package including this readme and sample WEB-API code here.

1.3 Architecture

The following diagram show the architecture of the solution:

It basically consists of 2 parts:

2. Installation

As the solution has 2 parts these need to be installed and setup. This and following chapters describe the steps required either to be done on Server or Client for various ways of authentication.

2.1 Server

Get the sso_server.zip and unzip its contents to server installation directory - usually /opt/OV/sd/server on HP-UX and Solaris or C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\server\ on Windows. It contains the following structure:


Note: If you are running on Java 1.3.x you will need to get Java Secure Socket Extensions. Copy files jcert.jar, jnet.jar, jsse.jar from the JSSE archive's lib directory into lib/hotfix/ (where sso.jar and ldap.jar reside).

2.2 Legacy Client

Get the sso_client_legacy.zip and unzip its contents to legacy client's installation directory (usually C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\client\) It contains the following structure:

2.3 Client 2008

Get the sso_client_2008.zip and unzip its contents to client 2008 installation directory (usually C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\Client 2008\). It contains the following structure:

2.4 Web Console

Get the sso_web_console.zip and unzip its contents to Web Console installation directory. It contains the following structure:

2.5 WEB-API

Get the sso_web_api.jar and include it into your project. You will need to retain web-api.jar in the project as well.

2.6 Service Pages

Get the sso_service_pages.zip and unzip it into your Service Pages installation.
Warning! If you want to use Windows NT Domain authentication you need to update underlying Tomcat to at least 5.5 - see chapter 3.6.1
It contains the following structure:

3. Configuration

3.1 Server

3.1.1 sso_settings.xml

This is the main file controlling the ServerHelper functioning. Follows description of its structure:

Remark: If you do not want to use one of the types (i.e. WEB-API or NT-DOMAIN or LDAP SSO), just comment the appropriate tag out or leave the attrinute values empty.

3.1.2 AFQ files

AFQ is the extension of saved Advanced Find Queries. They server as bridge between information provided from clients and Person records stored in ServiceDesk. You will create (or modify provided ones) AFQs using client and then copy the files to a server location pointed to by sso_settings.xml.

You will have to use special variables inside AFQ. These will be replaced with real values while processing each request. It is the same concept as special variables like $APPLICATIONSERVER$, $HOSTNAME$, $IPADDRESS$, $ACCOUNTNAME$ that were introduced in SP7. Here is a table containing variables names for Windows NT domain information. You will use these to find appropriate Person record for client SSO.

variable name sample value
$NT_DOMAIN$ MYDOMAIN
$NT_DOMAIN_SID$ S-1-5-21-436374069-1757981266-725345543
$NT_GROUP_IDS$ {S-1-1-0; S-1-5-32-544; S-1-5-32-545; S-1-5-4; S-1-5-11; S-1-5-5-0-69352; S-1-2-0}
$NT_IMPERSONATION_TOKEN$ 304
$NT_NAME$ rskolnik
$NT_PRIMARY_GROUP_ID$ S-1-5-21-436374069-1757981266-725345543-513
$NT_USER_SID$ S-1-5-21-436374069-1757981266-725345543-500

Remark: Web Console configured for Windows NT Domain SSO only provides values for $NT_DOMAIN$ and $NT_NAME$, the rest is empty.
For LDAP authentication the ServiceDesk server will receive these information about clients already authenticated by LDAP server

variable name sample value
$LDAP_URL$ ldap://ldap.skolnik.info
$LDAP_USERNAME$ rskolnik
$LDAP_PRINCIPAL$ uid=rskolnik,ou=people,o=street,dc=skolnik,dc=info

Situation is different with WEB-API requests as these come from a single place (usually your WEB server) where the information about the remote user may not necessarily be linked to Windows NT domain or LDAP tree at all or it may not be available. For example if users log into your corporate portal you will probably know the user's identification relevant to that portal. That is why when using WEB-API SSO it is up to you to provide the set of variables (in client SSO the Windows NT domain will do that instead of you). See 4.4 WEB-API usage for details.

3.1.3 General requirements

3.1.3.1 Display Logon Screen On Startup

You need to disable the option "Display Logon Screen On Startup" in General Settings. If you don't this setting will override SSO and will ask users for username and password on each client startup.

3.1.3.2 Password Validity Policy

Internally the ServiceDesk passwords are still being active in ServiceDesk database (I would have to change HP's code to turn it off). So you need to turn off the password validity restrictions or change the passwords periodically to some random values. If you let the passwords in database expire it will not let the users with expired passwords run the client.

3.2 Legacy Client

If the client wants to start without user intervention it needs to know one thing: ServiceDesk server's address. All the other info is retrieved from Windows NT domain or LDAP directory and handled by ServerHelper. So the SSO part on client will query configured accounts and will use the server's address from the default one. So make sure each client has one default account defined. The only important thing is to have correct Server name defined, cccount name and password can be set to bogus values for Windows NT authentication. For LDAP authentication correct Server is needed and stored username and password will be pre-filled (that means you can store your LDAP credentials there and then just hit OK when logon window appears).

Remark: This is usually needed only with new client installations. Existing clients usually have the default account defined and pointing to correct server.

3.3 Client 2008

The same thing applies here as with legacy client - the user has to have default account defined in order to get SSO working.

3.4 WEB-API

No special configuration is required to start using WEB-API SSO.

3.5 Web Console

3.5.1 Windows NT Domain Authentication

Rename OVPortalConfig.xml.JCIFS to OVPortalConfig.xml in %WEB_CONSOLE_HOME%/SIP/conf/framework/ and rename web.xml.JCIFS to web.xml in %WEB_CONSOLE_HOME%/SIP/webapps/ovportal/WEB-INF/. Edit JCIFS parameters for Windows NT Domain in %WEB_CONSOLE_HOME%/SIP/webapps/ovportal/WEB-INF/web.xml. Have a look here for other possible options you may need to use. Read the chapter on Transparent Authentication and the Network Password Dialog where you can find info required to ensure that transparent authentication will work for users without Network Password Dialog popping up and asking for NT username/password/domain.

3.5.2 LDAP Delegation

Rename OVPortalConfig.xml.LDAP to OVPortalConfig.xml in %WEB_CONSOLE_HOME%/SIP/conf/framework/. The LDAP settings are retrieved from server's configuration.

3.6 Service Pages

3.6.1 Windows NT Domain Authentication

Here's a step by step guide for configuring it:

  1. Install Apache Tomcat (version 5.5 or higher is required!) and Java Runtime if needed
  2. Copy webapps/sd-sp45/* from original Service Pages installation into webapps directory of your new Tomcat
  3. Extract files from sso_service_pages.zip into new Tomcat's directory.
  4. Rename web.xml.JCIFS to web.xml in webapps/sd-sp45/WEB-INF/
  5. Update following data in web.xml to reflect your settings:
  6. Review the mapping in web-api.afq and modify if necessary. Do not forget to restart ServiceDesk server if you modify the AFQ. By default it will try to lookup the Person record with Source ID being $NT_DOMAIN$\$NT_NAME$ These 2 variables will will contain real NT domain name and login name of remote user as provided by JCIFS NtlmHttpFilter.

3.6.2 LDAP Delegation

Rename ControlSet.jsp.LDAP to ControlSet.jsp and LoginLDAP.jsp.LDAP to LoginLDAP.jsp in %SERVICE_PAGES_HOME%/webapps/sd-sp45/. The LDAP settings are retrieved from SD server's configuration.

4. Usage

4.1 Server

The server part gets initialized upon receiving first request (not when the server starts!). You can find all the messages in standard log file log/logserver.txt and they have a category of <SSO> Here is an example from the log showing ServerHelper initialization with both NT-DOMAIN, LDAP and WEB-API debug turned on: 

So, 14/06/2008 22:25:41  Starting ServerHelper initialization...
So, 14/06/2008 22:25:41  Loading NT-DOMAIN filter from C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\server\client.afq
So, 14/06/2008 22:25:41  Loaded filter id=281485969981778 compound:
        Source ID is (exactly) $NT_DOMAIN$\$NT_NAME$
AND Account;Blocked equals No
So, 14/06/2008 22:25:41  Loading WEB-API filter from C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\server\web-api.afq
So, 14/06/2008 22:25:41  Loaded filter id=281485975683167 compound:
        Account;Login name is (exactly) $USER_ID$
AND Account;Blocked equals No
So, 14/06/2008 22:25:41  Loading LDAP filter from C:\Program Files\Hewlett-Packard\OpenView\service desk 4.5\server\ldap.afq
So, 14/06/2008 22:25:41  Loaded filter id=281485975683362 compound:
        Account;Login name is (exactly) $LDAP_USERNAME$
AND Account;Blocked equals No
So, 14/06/2008 22:25:41  ServerHelper Succesfully initialized, registered to Radovan Skolnik

4.1.1 Diagnostics

Upon receiving request the ServerHelper replaces variables in loaded AFQ with values from that request and performs the search. If you have turned on debugging the log will contain something like this: 

So, 14/06/2008 22:27:00 <SSO> Processing request NT-DOMAIN:1 containing variables [($NT_DOMAIN$=REXVMWARE); ($NT_NAME$=Administrator); ($NT_GROUP_IDS$={S-1-1-0; S-1-5-32-544; S-1-5-32-545; S-1-5-4; S-1-5-11; S-1-5-5-0-69352; S-1-2-0}); ($NT_USER_SID$=S-1-5-21-436374069-1757981266-725345543-500); ($NT_PRIMARY_GROUP_ID$=S-1-5-21-436374069-1757981266-725345543-513); ($NT_DOMAIN_SID$=S-1-5-21-436374069-1757981266-725345543); ($NT_IMPERSONATION_TOKEN$=304)] resulting into search query
        Source ID is (exactly) MYDOMAIN\rskolnik
AND Account;Blocked equals No
There are 5 possible outcomes for the search:

4.2 Legacy Client

4.2.1 Windows NT Domain authentication

You can start the client by running provided sd_client_nt.bat script. If you have overwritten sd_client.ini with contents of sd_client_nt.ini existing shortucts in Start Menu and Quick Launch created by ServiceDesk client installer will start to work as Windows NT Domain SSO as well. You can use all the original command line switches and they will function as expected except /USERNAME=... and /PASSWORD=.... These will not work because SSO is in effect and these do not fit in there. The following command line switches have additional functionality:

4.2.2 LDAP delegation authentication

You can start the client by running provided sd_client_ldap.bat script. The same applies as in Windows NT Domain authentication mode regarding command line switches. Unlike in Windows NT Domain case the user credentials cannot be obtained automatically from running system but user first needs to authenticate against LDAP server (it's configuration is retrieved from sso_settings.xml defined on ServiceDesk server). So the user is first shown login screen and when authenticated the information (those variables like $LDAP_USERNAME$, $LDAP_PRINCIPAL$, ...) is sent to ServerHelper to provide pre-authenticated session. If you have overwritten sd_client.ini with contents of sd_client_ldap.ini existing shortucts in Start Menu and Quick Launch created by ServiceDesk client installer will start to work as LDAP Delegation SSO as well.

4.3 Client 2008

4.3.1 Windows NT Domain authentication

You can start the client by running provided sso_nt.exe launcher. If you have overwritten servicedesk.ini with contents of sso_nt.ini existing shortucts in Start Menu and Quick Launch created by ServiceDesk client installer will start to work as Windows NT Domain SSO as well. You can use all the original command line switches and they will function as expected except /USERNAME=... and /PASSWORD=.... These will not work because SSO is in effect and these do not fit in there. The following command line switches have additional functionality:

4.3.2 LDAP delegation authentication

You can start the client by running provided sso_ldap.exe launcher. The same applies as in Windows NT Domain authentication mode regarding command line switches. Unlike in Windows NT Domain case the user credentials cannot be obtained automatically from running system but user first needs to authenticate against LDAP server (it's configuration is retrieved from sso_settings.xml defined on ServiceDesk server). So the user is first shown login screen and when authenticated the information (those variables like $LDAP_USERNAME$, $LDAP_PRINCIPAL$, ...) is sent to ServerHelper to provide pre-authenticated session. If you have overwritten servicedesk.ini with contents of sso_ldap.ini existing shortucts in Start Menu and Quick Launch created by ServiceDesk client installer will start to work as LDAP Delegation SSO as well.

4.4 WEB-API ApiSDSession

4.4.1 WEB-API ApiSDSession

The only thing you need to do to retrieve authenticated WEB-API session for a certain user is calling openSession static method from ApiSDSessionHelper class: 

package info.skolnik.radovan.hpovsd45.sso;

public class ApiSDSessionHelper {

    public static com.hp.itsm.api.ApiSDSession openSession(String sd_server, String secretKey, java.util.Hashtable variables, boolean debug) throws Exception {}
}
As mentioned previously the WEB-API SSO is a bit different from NT-DOMAIN SSO. The main difference is that in NT-DOMAIN case the information being used is Windows NT domain information of the user running the client while in WEB-API SSO case the user is usually sitting behind his browser and this part runs on WEB server. The most common case for WEB-API SSO would be using it on WEB server that serves some WEB-API application like Service Pages. By using some mechanism (for example JCIFS for Windows NT domain information) to find information about the user behind browser. You will provide this information as pairs of {String variableName, variableValue} that you put into java.util.Hashtable instance and send to ServerHelper. The same variableName(s) should be used in your WEB-API AFQ so that upon arrival of request they can be replaced by variableValue(s) and thus find the required Person record.

There is a similar class for getting ApiSDSession based on LDAP credentials (using LDAP AFQ): 
package info.skolnik.radovan.hpovsd45.sso;

public class ApiSDSessionLDAPDelegator {

    public static com.hp.itsm.api.ApiSDSession openSession(String sd_server, String ldap_username, String ldap_password, boolean debug) throws Exception {}
}

4.4.2 WEB-API example

Here is a sample code of WebApiSsoDemo.java that shows the usage of ApiSDSession openSession(String server, String secretKey, Hashtable variables, boolean debug) method. This sample expects mapping from the WEB-API AFQ provided in this package (i.e. Person record having Source ID like DOMAINNAME\USERNAME of the appropriate NT user): 

import java.util.Hashtable;  // this is part of Java Runtime
import com.hp.itsm.api.interfaces.*;  // these reside in web-api.jar so be sure to include it in the classpath
import com.hp.itsm.api.ApiSDSession;  // this one reside in web-api.jar as well
import info.skolnik.radovan.hpovsd45.sso.ApiSDSessionHelper;  // this one if from sso_web_api.jar so include that in classpath too


public class WebApiSsoDemo {

  public static void main(String args[]) {
    if (args.length != 3) {
      System.err.println("Usage: WebApiSsoDemo <server> <secret_key> <NT_Domain_Name> <NT_Domain_Login>");
      System.exit(1);
    }
    try {
      // fill up Hashtable with your variables and their respective values
      Hashtable vars = new Hashtable();
      // we put values here as to satisfy sample AFQ filter
      vars.put("$NT_DOMAIN$", args[2]);
      vars.put("$NT_NAME$", args[3]);

      // retrieve session - it should be a session for s Person who's Source ID matches $NT_DOMAIN$\$NT_NAME$ (or 2nd_cli_argument\3rd_cli_argument)
      // so be sure to update some Person's Source ID this way before running this otherwise you won't get any match.
      // Or you can change the AFQ to suit your mappings
      ApiSDSession session = ApiSDSessionHelper.openSession(args[0], args[1], vars, true);

      // we will dump some values to show we got the appropriate record

      IAccount account = session.getCurrentAccount();
      System.out.println("Account: Display name='" + account.getDisplayName() + "' Login name='" + account.getLoginName() + "'");
      IPerson persons[] = account.getPerson_Account();
      // there should be at most one such record
      if ((persons != null) && (persons.length > 0)) {
        System.out.println("Person: Name='" + persons[0].getName() + "' Searchcode='" + persons[0].getSearchcode() + "'");
      }
      // just exit now

      System.exit(0);

    } catch (Exception ex) {
      System.err.println("Oopppss - something unexpected happened: " + ex);
      System.exit(2);
    }
  }

}
So if you use provided sso_settings.xml and web-api.afq and will run the WebApiSsoDemo.bat like this (be sure to put current version of web-api.jar to zip directory for it to work): 
    C:\sso>WebApiSsoDemo.bat localhost M8_S3cr3t#K3y! SKOLNIK_INFO Administrator
you will get output like similar to this: 
    Be sure to copy web-api.jar to zip directory!!!
    Account: Display name='System administrator' Login name='system'
    Person: Name='User, System' Searchcode='SYSTEM'
So in the WEB-API AFQ the variable $NT_DOMAIN$ has been filled in with value SKOLNIK_INFO and $NT_NAME$ has been filled in with value Administrator. That search found Person record assigned to system account and WEB-API session was retrieved for it. Then some attributes were printed of that Person as well assigned Account.

4.5 Web Console

If any of the modes is not working as expected you can change tracingLevel="tracing" in %WEB_CONSOLE_HOME%/SIP/conf/framework/OVPortalConfig.xml to increase the amount of logged information. Restart Web Console and the information will be logged into %WEB_CONSOLE_HOME%/SIP/log/sip.trace.

4.5.1 Windows NT Domain authentication

Open up Web Console in your web browser - it should let you in without asking for username and password (this works the same way as Service Pages with JCIFS - see chapter 4.4.4). If not, you can check %WEB_CONSOLE_HOME%/SIP/log/sip.trace and logserver.txt on SD server to see what happened.

4.5.2 LDAP delegation authentication

Open up Web Console in your web browser. Provide your LDAP username and password and it should let you in. If not, you can check %WEB_CONSOLE_HOME%/SIP/log/sip.trace and logserver.txt on SD server to see what happened.

4.6 Service Pages

4.6.1 Windows NT Domain authentication

  1. Start the Tomcat and open Service Pages application. It should be http://tomcat_ip_address:8080/sd-sp45/index.html If everything works you should be presented with Service Pages interface where you are already logged in.
  2. In case Network Password Dialog appears read the chapter on Transparent Authentication and the Network Password Dialog where you can find info required to ensure that transparent authentication will work for users without Network Password Dialog popping up and asking for NT username/password/domain.
Here follows a description of how the whole solution works.

  1. The user starts browser and requests a page.
  2. The requests arrives to Tomcat. Before the page is served the request is passed through javax.servlet.Filter chain configured for the application.
  3. jcifs.http.NtlmHttpFilter is the first one in chain and in the background it will negotiate the NTLM hashes between user's browser and NT Domain controller. If succesfull it will make available remote user's identification in the form of DOMAINNAME\USERNAME.
  4. Next in chain is info.skolnik.radovan.hpovsd45.sso.HttpFilter. It will check if the SdClientBean is already registered in the session. If this is the first requested page the bean is not there yet and it will extract the information from previous filter, parse it and fill it into variable pairs and send them to SSO ServerHelper via SdClientBeanHelper.getSdClientBean. ServerHelper will run the configured AFQ after replacing symbolic variable names with real values that came in and if succesfull will provide SdClientBean back to HttpFilter which will store it into session. When next requests are processed this step is skipped as the bean already exists in the session.
  5. Finally a requested page is being processed. As the SdClientBean is already registered in the session it will seem (and rightly so) to all the JSPs that the login has already been passed. Page is rendered and sent back to client.

4.6.2 LDAP delegation authentication

Open up Service Pages in your web browser, in the left menu you should see LDAP Login entry. Click on it. Provide your LDAP username and password and it should let you in. If not, you can check Service Pages Tomcat's logs and logserver.txt on SD server to see what happened.

4.6.3 Service Pages SdClientBean

Service Pages do not directly use ApiSDSession object but instead use SdClientBean which is a wrapper around ApiSDSession. To enable you using SSO with Service Pages without rewriting the source JSPs there is a helper class that provides the same functionality as ApiSDSessionHelper but returns pre-authenticated SdClientBean. 

package info.skolnik.radovan.hpovsd45.sso;

public class SdClientBeanHelper {

    public static SdClientBean getSdClientBean(String sd_server, String secretKey, Hashtable variables, boolean debug) throws Exception {}
}
Also for retrieving SdClientBean based on LDAP credentials there is a similar helper class: 
package info.skolnik.radovan.hpovsd45.sso;

public class SdClientBeanLDAPDelegator {

    public static SdClientBean getSdClientBean((String sd_server, String ldap_username, String ldap_password, boolean debug) throws Exception {
}

5. Additional info

5.1 Demo limitations

Unless you purchase a license (and enter the serialNumber into sso_settings.xml) the ServerHelper will run in demo mode. That means it will process SSO requests for one hour from the first request. After that all the SSO requests will be denied. If you restart the server the demo timer will be reset. In no way will functioning of ServiceDesk server existing functionality be affected in any case (before or after the demo period). Please send licensing enquiries here.

5.2 Compatibility

The package does not use any specific Service Pack functionality - as far as I can tell it will work on any SP used nowadays.

5.3 Future plans

At this point this does everything I wanted it to. I will fix bugs if any should occur. If you have some requirements or cool suggestions, just let me know...

6. History