v1.0 | Aaron Chandler

SSL and TRUSTED SIGN-ON for HP SERVICE MANAGER

Revision History

Date Description Author13JUL2012 Initial Draft – v0.1 – This established the format for the document and

completed the baseline documentation.Chandler

16JUL2012 Initial Draft – v0.2 – This revision added further documentation. Chandler17JUL2012 V1.0 – This revision added further documentation and established the

first completed draft.Chandler

Table of ContentsExecutive Summary.....................................................................................................................................4

ASSUMPTIONS.............................................................................................................................................5

SECURE SOCKET LAYER (SSL).......................................................................................................................6

A: Generate the Server Certificates for the Application Server (pre-KM1288853)..................................6

B: Generate the Client Certificates for the Application Server and Web Server (pre-KM1288853).........8

C: Configure the SM Application to run in SSL.......................................................................................10

D: Connect with the SM Thick Client over SSL.......................................................................................11

E: Verify the Thick Client SSL connection to the SM Application...........................................................12

F: Connect with the Web Tier over SSL..................................................................................................13

G: Verify the Web Tier SSL connection to the SM Application...............................................................15

TRUSTED SIGN-ON (TSO)...........................................................................................................................16

H: Configure the SM Application for Trusted Sign-On...........................................................................16

I: Connect with the Thick Client via TSO over SSL..................................................................................17

J: Connect with the Web Client via TSO over SSL...................................................................................18

Executive SummaryThe purposes of this document are these:

1. Describe in practical "real-world applicable" terminology the steps required to configure an instance of HP Service Manager (SM), already existing within a given environment, to run as an application in, and accept connections over, Secure Socket Layer (SSL).

2. Describe, in similar terms, the procedures to configure the same instance of HP Service Manager, now running in, and accepting clients over, SSL, to utilize the SM pass-through authentication feature known as Trusted Sign-On (TSO).

3. Provide various and sundry files which may be required or useful in the actual execution of the steps described above.

ASSUMPTIONS

For the purposes of this document, it will be assumed that the reader is implementing SSL and TSO into a given environment (i.e. Dev, Test, Prod, DR, etc.). It will further be assumed that the architecture of this implementation is that of a standard SM small deployment, namely a single application server and a single web server (we will not be concerned with the SM database tier for this document). Therefore, when referring to servers, this document will reference them in this way:

Application Server:Shortname: sm_appFQDN: sm_app.itsm.intact-tech.comIP: 1.22.333.4

Web Server:Shortname: sm_webFQDN: sm_web.itsm.intact-tech.comIP: 1.22.333.5

This document will also assume the following:

1: The reader is permitted to utilize self-created and self-signed certificates for his/her SSL needs. If this is not the case, then this document suggests providing the appropriate sections to the certificate authorities for the environment in which SSL and TSO are being implemented.

2: An install of the SM thick/full/fat client has been performed on the application server.

3: The reader is implementing HP Service Manager 9.x.

4: The reader does not need advanced instructions concerning the starting and stopping of Windows Services.

5: The implementation of SM is using Apache Tomcat for its main web tier environment and Microsoft IIS for authentication with TSO.

6: Microsoft IIS has already been installed (either by server administrators or by the reader) with the appropriate roles needed for ISAPI redirection.

7: Tomcat has been installed with 8080 as its default port (as opposed to 80).

SECURE SOCKET LAYER (SSL)

A: Generate the Server Certificates for the Application Server (pre-KM1288853)

NOTE: For this step, refer to the files included in the included pre-KM1288853 directory.

We are concerned primarily with one batch file in this folder, namely tso_srv_svlt.bat. This will be used to create server certificates for the SM application server.

1: Create a directory named certs on the C: drive of the machine upon which you are creating the certificates. Place the files from the included pre-KM1288853 directory in this certs folder. Edit the aforementioned .bat file, and find the following line:

set JAVA_HOME="C:\Program Files (x86)\Java\jre6"

2: Edit this line to reflect the location of the JAVA_HOME variable of the machine on which you are creating the certificates. If there is no JAVA_HOME variable established on this machine, this value needs to be the highest-level directory of an installed instance of Java which has a keytool.exe in the /bin/ directory.

3: Open a command prompt, and navigate to the certs directory on C:. Run the following command:

C:\certs>tso_srv_svlt.bat

This command initiates the batch file which will create the server-side certificates for SM.

4: In the course of this batch file, you will be required to enter information at various points. The questions and answers are determined by the openssl.conf file, and the defaults will be these:

Question: Country Name (2 letter code) [US]:Answer: <Two-Letter abbreviation for the country in which the application server resides>Question: State [MD]:Answer: <Two-letter abbreviation for the state in which the application server resides>Question: Locality Name (eg, city) [GREENBELT]:Answer: <Name of city or other distinguishing locale in which the application server resides>Question: Organizational Name [INTACT TECHNOLOGY]:Answer: <High-level designator of the company or group or agency to which the application server belongs>Question: Organizational Unit Name (eg, section) [ITSM]:Answer: <Actual-level designator of the company or group or agency (within the larger organization as indicated above) to which the application server belongs>Question: Common Name (eg, computer hostname) [server.domain.com]:

Answer: <FQDN of the application server; for the purposes of this document: sm_app.itsm.intact-tech.com>Question: Email Address [user@domain.com]:Answer: <Email address of either the individual generating the certificates or the individual who will be responsible for the servers post-implementation>

5: After entering the above information, the batch file will proceed to create the necessary files and insert them into the necessary keystores in order to accomplish the certification process for the application server. Shortly thereafter, you will again be required to enter information for the process to continue, namely:

Question: What is your first and last name? [Unknown]:Answer: <FQDN of the application server; for the purposes of this document: sm_app.itsm.intact-tech.com>Question: <The batch file will now, in reverse order, ask you the same questions as it did above. Respond with the same answers as above. When asked to confirm your responses, answer y>

6: You will now be asked to enter a password for the server.keystore which the batch file is creating. This password is already specified in the batch file as serverkeystore. Simply press Enter to use this default password. The batch will complete soon after.

7: There will be three new folders inside the C:\certs directory, namely certs, crs, and key. From the C:\certs\certs folder, copy the file cacerts and paste it into the directory <SM Installation Folder>\Server\RUN.

NOTE: Always back up any files which may be overwritten, i.e. cacerts.BAK

8: From the C:\certs\key folder, copy the file server.keystore and paste it into the directory <SM Installation Folder>\Server\RUN.

The server-side certificates for the application server have been generated and staged.

B: Generate the Client Certificates for the Application Server and Web Server (pre-KM1288853)

NOTE: For this step, refer to the files included in the included pre-KM1288853 directory.

We are concerned primarily with one batch file in this folder, namely tso_cln_svlt.bat. This will be used to create client certificates for the SM application server and web server.

1: Create a directory named certs on the C: drive of the machine upon which you are creating the certificates. Place the files from the included pre-KM1288853 directory in this certs folder. Edit the aforementioned .bat file, and find the following line:

set JAVA_HOME="C:\Program Files (x86)\Java\jre6"

2: Edit this line to reflect the location of the JAVA_HOME variable of the machine on which you are creating the certificates. If there is no JAVA_HOME variable established on this machine, this value needs to be the highest-level directory of an installed instance of Java which has a keytool.exe in the /bin/ directory.

3: Open a command prompt, and navigate to the certs directory on C:. Run the following command followed by the FQDN of the server for which you are creating client certificates (i.e. sm_web.itsm.intact-tech.com):

C:\certs>tso_cln_svlt.bat sm_web.itsm.intact-tech.com

This command initiates the batch file which will create the server-side certificates for SM.

4: In the course of this batch file, you will be required to enter information at various points in a similar fashion to those asked during the execution of Section A. You must respond to the questions with the same answers as you did in that Section (with the exception of "What is your first and last name? [Unknown]:" – the answer to this question is the FQDN of the server for which you are creating client certificates).

5: After entering the above information, the batch file will proceed to create the necessary files and insert them into the necessary keystores in order to accomplish the certification process for the application server. Shortly thereafter, you will be asked to enter a password for the server.keystore which the batch file is creating. This password is already specified in the batch file as serverkeystore. Simply press Enter to use this default password.

6: You will be asked to "Trust this certificate?" If you have correctly entered all the requested information, then you may trust it, and therefore should enter y. The batch will complete soon after.

7: From the C:\certs\certs folder, copy the file trustedclients.keystore and paste it into the directory <SM Installation Folder>\Server\RUN.

8: From the C:\certs\certs folder, copy the file cacerts and paste it into the WEB-INF directory of the Service Manager webapp folder within Tomcat on the web machine itself.

9: From the C:\certs\key folder, copy the file <client machine FQDN>.keystore (in this instance, sm_web.itsm.intact-tech.com.keystore) and paste it into the WEB-INF directory of the Service Manager webapp folder within Tomcat on the web machine itself.

The client-side certificates for the web server have been generated and staged.

Proceed to execute steps 1-7 again, this time substituting the FQDN of the application server for the FQDN of the web server, i.e. sm_app.itsm.intact-tech.com instead of sm_web.itsm.intact-tech.com.

8: From the C:\certs\certs folder, copy the file cacerts and paste it into the directory <SM Installation Folder>\Client\plugins\com.hp.ov.sm.client.common_<version>.

9: From the C:\certs\key folder, copy the file <client machine FQDN>.keystore (in this instance, sm_app.itsm.intact-tech.com.keystore) and paste it into the directory <SM Installation Folder>\Client\plugins\com.hp.ov.sm.client.common_<version>.

The client-side certificates for the application server have been generated and staged.

C: Configure the SM Application to run in SSL

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the HP Service Manager 9.x Windows Service and the sm.ini, found in the \RUN folder. We will edit this file to add parameters which will constrict the application to running in SSL.

1: On the server sm_app, Stop the Windows Service HP Service Manager 9.x.

2: Navigate to the location <SM Installation Folder>\Server\logs. Delete all files within this folder.

3: Navigate to the location <SM Installation Folder>\Server\RUN. Edit the file sm.ini.

4: The following initialization parameters need to be modified to read thusly, or entered if they are not already present:

keystoreFile:server.keystorekeystorePass:serverkeystoretruststoreFile:cacertstruststorePass:changeitssl_trustedClientsJKS:trustedclients.keystoressl_trustedClientsPwd:trustedclientsssl:1ssl_connector:1trustedsignon:0ssl_reqClientAuth:0

5: Once the sm.ini file has been saved and closed, Start the Windows Service HP Service Manager 9.x.

D: Connect with the SM Thick Client over SSL

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the SM Thick Client and the com.hp.ov.sm.client.common plugin folder. We will set preferences which will allow the Thick Client to connect to the application over SSL.

1: Load the HP Service Manager Thick Client by clicking Start>All Programs>HP> Service Manager 9.30> Service Manager Client.

2: When the client application loads, click Close on the Connections window, and then Window>Preferences.

3: Drill down into the HP Service Manager section, and then click Security.

4: Ensure that the CA certificates file parameter contains the full path and filename of the cacerts file which you earlier pasted into the common plugin folder earlier, i.e. <SM Installation Folder>\Client\plugins\com.hp.ov.sm.client.common_<version>\cacerts

5: Ensure that the Client keystore file parameter contains the full path and filename of the <clientname>.keystore file which you earlier pasted into the common plugin folder earlier, i.e. <SM Installation Folder>\Client\plugins\com.hp.ov.sm.client.common_<version>\ sm_app.itsm.intact-tech.com.keystore

6: Ensure that the Client keystore password parameter contains the password to the <clientname>.keystore file which you earlier pasted into the common plugin folder earlier, i.e. clientkeystore.

7: Click Apply and then OK. Close the Thick Client application. Re-open the Thick Client application as done in Step 1 above.

8: In the Connections window, on the Connection tab, type falcon in the user name field. Leave the password field blank. In the Server host name field, type the FQDN of the application server, i.e. sm_app.itsm.intact-tech.com. In the Server port number field, type the applicable port for your environment, i.e. 13080.

9: In the Connections window, on the Advanced tab, ensure that Use SSL Encryption is checked.

10: Click Apply, and then click Connect. You will be logged into SM.

E: Verify the Thick Client SSL connection to the SM Application

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the sm.log file located in the <SM Installation Folder>\Server\logs directory. We will utilize this file to investigate and verify if we have successfully connected to the application over SSL.

1: Access the file sm.log located in the <SM Installation Folder>\Server\logs directory.

2: Near the bottom of the file there should be a line noting that the user falcon has logged into the system. Accompanying this login there should be a line reading SSL connection accepted. If this line is present, then you have successfully connected to the application over SSL with the Thick Client.

F: Connect with the Web Tier over SSL

NOTE: For this section, we will be operating exclusively on the server sm_web.

We are concerned primarily with the web.xml file found in the WEB-INF directory of the SM Tomcat webapp folder. We will set parameters to force the web tier to connect to the SM application over SSL.

1: Stop the Windows Service Apache Tomcat.

2: Navigate to the folder <Tomcat SM webapp Directory>\WEB-INF.

3: Edit the file web.xml to change the following parameters:

NOTE: You may need to either run Notepad as an administrator or modify the permissions on the Tomcat folder in order to edit this file.

Default:<param-name>isCustomAuthenticationUsed</param-name><param-value>true</param-value>

Change:<param-name>isCustomAuthenticationUsed</param-name><param-value>false</param-value>

Default:<param-name>serverHost</param-name><param-value>localhost</param-value>

Change:<param-name>serverHost</param-name><param-value><FQDN of application server, i.e. sm_app.itsm.intact-tech.com ></param-value>

Default:<param-name>ssl</param-name>

<param-value>false</param-value>Change:

<param-name>ssl</param-name> <param-value>true</param-value>Default:

<param-name>keystore</param-name><param-value/>

Change:<param-name>keystore</param-name><param-value><web server cert, i.e. sm_web.itsm.intact-tech.com.keystore></param-value>

Default:<param-name>keystorePassword</param-name><param-value/>

Change:<param-name>keystorePassword</param-name><param-value><web server cert password, i.e. clientkeystore></param-value>

4: Start the Windows Service Apache Tomcat.5: Access the SM web client (i.e. http:// sm_web.itsm.intact-tech.com:8080/sm).

6: Enter credentials for an operator ID other than falcon and click Log In. You will be logged into SM.

G: Verify the Web Tier SSL connection to the SM Application

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the sm.log file located in the <SM Installation Folder>\Server\logs directory. We will utilize this file to investigate and verify if we have successfully connected to the application over SSL.

1: Access the file sm.log located in the <SM Installation Folder>\Server\logs directory.

2: Near the bottom of the file there should be a line noting that the user from Step 6 of the previous section has logged into the system. Accompanying this login there should be a line reading SSL connection accepted. If this line is present, then you have successfully connected to the application over SSL with the Web Client.

HP Service Manager is now fully running in and accepting connections over SSL. The vast majority of your users will be connecting over SSL. If the need exists for additional thick clients (for developers or administrators) to connect to the application, then Section B will need to be repeated for those client machines. Alternatively, you may configure an additional SM servlet to run without SSL, and those thick client machines can connect to that servlet.

It is prudent to fully configure the SSL operation of the application prior to attempting to configure the TSO feature. In this way, if issues arise during the setup of one or the other, it will be clear whether the issue is SSL- or TSO-related. Now that SSL has been configured, we may turn our attention to configuring TSO.

TRUSTED SIGN-ON (TSO)

H: Configure the SM Application for Trusted Sign-On

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the sm.ini file found in the WEB-INF directory of the SM Tomcat webapp folder. We will change parameters to force the application to require Trusted Sign-On connections.

1: Stop the Windows Service HP Service Manager 9.x.

2: Navigate to the directory <SM Installation Folder>\Server\RUN. Edit the file sm.ini.

3: The following initialization parameters need to be modified to read thusly:

trustedsignon:1ssl_reqClientAuth:2

4: Once the sm.ini file has been edited, Start the Windows Service HP Service Manager 9.x.

I: Connect with the Thick Client via TSO over SSL

NOTE: For this section, we will be operating exclusively on the server sm_app.

We are concerned primarily with the SM Thick Client and creating an operator record in SM. After creating a new user account for TSO testing, we will tweak a preference to force the client application to the application via TSO over SSL.

1: Load the HP Service Manager Thick Client by clicking Start>All Programs>HP> Service Manager 9.30> Service Manager Client.

2: Log into the application and create an operator record. The name field in this operator needs to exactly match the domain user account which you are using to implement and/or test TSO. Ensure that the expire.password field on this operator record is set to FALSE. Log out of the application once the operator record has been created.

NOTE: If two different domain users are being used to test TSO – i.e. one to log into the application server to test with the thick client and one to access the web tier on a local workstation, then two operators will need to be created, one to match each user.

3: Open the Connections dialog in the thick client by clicking File>Connect…>Connections… and duplicate an existing connection. On the Connection tab, change the User name field to reflect the operator ID which you just created (the one which matches the domain user with which you are logged into the machine). Leave the Password field blank. In the Server host name field, type the FQDN of the application server, i.e. sm_app.itsm.intact-tech.com. In the Server port number field, type the applicable port for your environment which is constrained to require TSO, i.e. 13080. Ensure that the Use Trusted Sign-On radio button is selected, rather than the Use Login/Password radio button. On the Advanced tab, ensure that Use SSL Encryption is checked.

4: Click Apply, and then click Connect. You will be logged into SM.

There is no verification needed to ensure that the thick client has connected to the application via TSO. If the connection attempt was successful, assuming that Use Trusted Sign-On was selected and that the client was directed to the correct port (i.e. not a servlet configured for non-TSO for any reason), then the connection properly occurred via TSO and the feature has been correctly configured in the SM application itself.

J: Connect with the Web Client via TSO over SSL

NOTE: For this section, we will be operating exclusively on the server sm_web.

We are concerned with an ISAPI filter between IIS/Tomcat and multiple .xml files in the Tomcat directory. We will configure this ISAPI filter to pass the name of the user to SM in the http header, and we will configure Tomcat-wide files as well as webapp-specific files for SM, in order to facilitate the TSO feature for application users.

1: Stop the Windows Service Apache Tomcat. Then create a folder inside the Apache Software Foundation folder named IIS_Tomcat.

NOTE: If you earlier modified the permissions on the Tomcat folder previously to facilitate editing the web.xml file, then place this IIS_Tomcat folder inside the Apache Software Foundation\Tomcat directory.

2: In this IIS_Tomcat folder, place the isapi_redirect.dll, isapi_redirect.properties, uriworkermap.properties, and workers.properties files.

3: Edit the isapi_redirect.properties file. You will need to ensure that the log_file=, worker_file=, and worker_mount_file= parameters are set to the correct location and filename.

4: Open Internet Information Services (IIS) Manager. You will now configure the ISAPI connector between IIS and Tomcat.

5: In the 'Connections' panel, ensure that the IIS Default Web Site is selected.

6: Double-click the 'ISAPI Filters' icon in 'Features View'.

7: In the 'Actions' panel on the right, select 'Add'.

8: Set the 'Filter name' to 'tomcat' and set the 'Executable' to the isapi_redirect.dll

9: Click 'OK'.

10: The new filter should now be listed in the ISAPI Filters list for the website.

11: In the 'Connections' panel, ensure that the default IIS Web Site is selected.

12: Right-click the IIS Web Site and select 'Add Virtual Directory'.

13: Set the 'Alias' to 'jakarta'.

14: Set the 'Physical Path' to the IIS_Tomcat directory which you created earlier.

15: Click 'OK'.

16: Verify that a 'jakarta' virtual directory is now present under the selected website.

17: Next, select the 'jakarta' virtual directory in the 'Connections' panel.

18: Double-click the 'Handler Mappings' icon in 'Features View'.

19: Click the 'Edit Feature Permissions' link in the 'Actions' panel.

20: Ensure that the 'Execute' option is selected.

21: Click 'OK'.

22: Select the IIS Default Web Site and double-click the 'Authentication' icon in 'Features View'.

23: Use the 'Disable' and 'Enable' items in the 'Actions' panel to ensure that 'Windows Authentication' is the only authentication method listed in the table as 'Enabled'.

24: In the 'Connections' panel, ensure that the local IIS Server is selected.

25: Double-click the 'ISAPI and CGI Restrictions' icon in 'Features View'.

26: Click 'Add' in the 'Actions' panel.

27: Set the 'ISAPI or CGI path' to the isapi_redirect.dll you downloaded in step 1.

28: Set the 'Description' to 'tomcat'.

29: Ensure that the 'Allow extension path to execute' is selected.

30: Click 'OK'.

31: Verify that the new ISAPI restriction is listed in the table with a restriction of 'Allowed'.

30: In the 'Connections' panel, ensure that the default IIS Web Site is selected.

31: Double-click the 'Request Filtering' icon in 'Features View' (If the Request Filtering icon is not displayed, you may need to install the Request Filtering Role Service to the Web Server Role).

32: Click the 'Edit Feature Settings' link in the 'Actions' panel.

33: Ensure that the 'Allow double escaping' option is selected.

34: Modify "Maximum allowed content length (bytes)" to the maximum size of attachments you want that your installation allows.

35: Click 'OK'. The ISAPI connection between IIS and Tomcat has been configured. If you connect to the web server in a browser with no port following the url, you should be directed to the default Tomcat

page. You will now proceed to edit two files – to permit (A) Tomcat in general and (B) the SM webapp specifically to connect to the SM application via TSO.

36: Navigate to the folder <Tomcat Installation Directory>\webapps\sm\WEB-INF\classes.

37: Edit the file application-context.xml. We will be editing a value within the filterChainProxy bean. You will note that after this bean, there are commented-out guidelines for enabling preauthentication. We will edit the file as specific in these guidelines. Find the following line and add preAuthenticationFilter to it thusly:

Default:/**=httpSessionContextIntegrationFilter,anonymousProcessingFilter

Change:/**=httpSessionContextIntegrationFilter,preAuthenticationFilter,anonymousProcessingFilter

38: Navigate to the folder <Tomcat Installation Directory>\conf.

39: Edit the file server.xml. Find the following parameter and add tomcatAuthentication="false":

Default:<!-- Define an AJP 1.3 Connector on port 8009 --><Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

Change:<!-- Define an AJP 1.3 Connector on port 8009 --><Connector port="8009" protocol="AJP/1.3" redirectPort="8443"

tomcatAuthentication="false"/>

40: Start the Windows Service Apache Tomcat.

41: Open a browser and enable Automatic Logon. Example in Internet Explorer: Tools>Internet Options>Security Tab>Internet/Local intranet>Custom Level>User Authentication>Logon>Automatic logon with current username and password.

42: In a browser, access the SM Web Client with the following URL: <FQDN of the web server>/sm, i.e. sm_web.itsm.intact-tech.com/sm. As long as an operator ID exists which matches the user with which you are logged into the machine on which you are using the browser, you will bypass the login screen and be directly logged into the application.

SSL and Trusted Sign-On are now both fully configured and your userbase may utilize the application using both features. Operator IDs will need to exist for every user which may access SM.