This edition applies to version 3, release 2, modification 0 of IBM® TRIRIGA®
Application Platform and to all subsequent releases and modifications until ...
IBM TRIRIGA Application Platform Version 3.2
Single Sign-On Setup User Guide
© Copyright IBM Corp. 2011
i
Note Before using this information and the product it supports, read the information in “Notices” on page 18.
This edition applies to version 3, release 2, modification 0 of IBM® TRIRIGA® Application Platform and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 2011. All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents ABOUT THIS GUIDE ...................................................................................................... 1 Conventions .................................................................................................................................................................. 1 Intended Audience ....................................................................................................................................................... 1 Prerequisites ................................................................................................................................................................. 1 Support ......................................................................................................................................................................... 1
1.
INTRODUCTION .................................................................................................... 2
2.
CONFIGURING MICROSOFT IIS WITH IBM TRIRIGA (JBOSS) ......................... 4
Setting up IIS 6 ............................................................................................................................................................ 4 Setting up IIS 7 ............................................................................................................................................................ 6 Troubleshooting ........................................................................................................................................................... 9
3.
SETTING UP SSO WITH IIS ................................................................................ 11
Configuring IBM TRIRIGA and IIS ....................................................................................................................... 11 Troubleshooting ......................................................................................................................................................... 12
4.
CONFIGURING APACHE WITH IBM TRIRIGA (JBOSS) ................................... 14
5.
SETTING UP SSO WITH APACHE ..................................................................... 15
INDEX ........................................................................................................................... 16 NOTICES ...................................................................................................................... 17
© Copyright IBM Corporation 2011.
About This Guide IBM® TRIRIGA® requires a user name and password to gain access to the applications. Many customers use single sign-on (SSO) to manage access by their users across the spectrum of applications in their environment. This guide describes how to set up single sign-on (SSO) for the IBM TRIRIGA Application Platform. It includes steps to allow users to sign in to IBM TRIRIGA with an existing user name and password stored in Active Directory.
Conventions This document uses the following conventions to ensure that it is as easy to read and understand as possible:
Note – A Note provides important information that you should know in addition to the standard details. Often, notes are used to make you aware of the results of actions.
Tip – A Tip adds insightful information that may help you use the system better.
Attention – An Attention notice indicates the possibility of damage to a program, device, system, or data.
Intended Audience This guide is intended for users responsible for establishing and maintaining the security of their company’s IBM TRIRIGA environment.
Prerequisites This guide assumes the reader understands the IBM TRIRIGA Application Platform and is well versed in software security and the sign-on security of their company’s environment.
Support IBM Software Support provides assistance with product defects, answering FAQs, and performing rediscovery. View the IBM Software Support site at www.ibm.com/support. •
© Copyright IBM Corporation 2011.
1
1. Introduction The information in this document guides you through configuring Web servers with Red Hat JBoss Application Server, then configuring with Single Sign-On (SSO) with those servers. SSO allows your users to sign in to IBM TRIRIGA with existing user names and passwords stored in an Active Directory or LDAP Server. As noted in this document, SSO does not always result in a seamless sign on. Configuring IIS with SSO involves two steps: •
Configure the Web server to pass Web requests to JBoss.
•
Set up SSO with the Web server.
This guide covers configuring IIS and Apache with JBoss. If you use WebSphere® or Oracle WebLogic application servers, refer to the IBM or Oracle/BEA for documentation on setting up those application servers with your Web server. Below is a diagram of an environment with a Web server that proxies requests from end users to an application server.
Example Environment The following identifies the flows in the example environment diagram above: •
Users first enter the Web Server URL in their browsers.
•
The Web Server will challenge the browser for their sign in information. (It will either prompt the user for a username and password, or seamlessly pass it over).
•
The Web Server will verify the information with the directory server.
•
If the login was successful, the Web server will append the user credentials to the HTTP header, and allow them to the Application Server.
•
The Application Server will process the user credentials and log them into the application.
© Copyright IBM Corporation 2011.
2
Note – Disable the ‘http’ port on the Application Server after the Web server configuration has completed.
© Copyright IBM Corporation 2011.
3
2. Configuring Microsoft IIS with IBM TRIRIGA (JBoss) Setting up IIS 6 Begin by setting up the mod_jk isapi_redirect dll. This can be downloaded from the Apache Tomcat Connectors Web site at http://www.apache.org/dist/tomcat/tomcatconnectors/jk/binaries/windows/ For the latest version, sort by Last Modified, and find the file called tomcat-connectors-X.X.XX-windows-i386-iis.zip To Set Up IIS 6 •
Make sure Microsoft IIS 6 is installed and can start with the default Under Construction page.
•
Download and unzip the file from the Apache Tomcat Connectors website (see above),
•
Open the mod_jk\Win32 folder and double click isapi_redirect.msi.
•
Choose a location to install the Apache Jakarta ISAPI Redirector. Typically, this location is C:\Inetpub\Jakarta.
Note – If you use a different location, make sure you write down the new location.
•
When the Installer is done, click Finish to close the window.
•
Open the C:\Inetpub\Jakarta\conf directory.
•
Rename the workers.properties.minimal file from that directory to workers.properties.
•
Tip – The C:\Inetpub\Jakarta\conf directory is created during the install of the Jakarta Isapi Redirector.
Edit workers.properties in the C:\Inetpub\Jakarta\conf directory with an editor like Notepad or WordPad. Replace the contents with the following and save: worker.list=ajp13 worker.ajp13.port=8009 worker.ajp13.host=$$TRIRIGA_APP_SERVER$$ worker.ajp13.type=ajp13 worker.ajp13.lbfactor=1 worker.ajp13.cachesize=10
•
Change $$TRIRIGA_APP_SERVER$$ to the hostname or IP address of your server. If IIS and JBoss are installed on the same server, use localhost.
© Copyright IBM Corporation 2011.
4
To Set Up IIS 6 •
Save the file.
•
Edit uriworkermap.properties in the C:\Inetpub\Jakarta\conf directory with an editor like Notepad or WordPad. If the uriworkermap.properties file is not present in the C:\Inetpub\Jakarta\conf directory, create it.
•
Clear the entire file.
•
Enter the following: /*=ajp13
Note – The above text should be the only entry in the file.
•
Save the file.
•
Open the Registry Editor with Regedit.
•
Navigate to: HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0
•
Edit the worker_file key.
•
Change the value data to: C:\Inetpub\Jakarta\conf\workers.properties
•
Click OK.
•
Right-click My Computer and select Manage.
•
Expand Services and Applications. Select and expand Internet Information Services (IIS) Manager.
•
Under IIS, expand the Web Sites directory.
•
In Web Service Extensions, click All Unknown ISAPI Extensions.
•
Click Allow.
•
Right-click Internet Information Services.
© Copyright IBM Corporation 2011.
5
To Set Up IIS 6 •
Select All Tasks. Then select Restart IIS.
•
Check to make sure the Default Web Site has started.
•
Right-click Default Web Site, select Properties, and select the ISAPI Filters tab.
•
If JBoss is not running, start JBoss.
•
Test the connection between the Web server and the application server by opening a browser on the server and entering: http://localhost/. The default sign in page will display.
Setting up IIS 7 To Set Up IIS 7 •
Download the 1.2.32 version of the isapi_redirect binary from the following URLs: For 32-bit: http://www.apache.org/dist/tomcat/tomcatconnectors/jk/binaries/windows/tomcat-connectors-1.2.32-windows-i386-iis.zip For 64-bit: http://www.apache.org/dist/tomcat/tomcatconnectors/jk/binaries/windows/ tomcat-connectors-1.2.32-windows-x86_64-iis.zip
•
Create a folder named Jakarta at the following location: C:\Inetpub\Jakarta
•
Create folders with the following names under the Jakarta folder: bin, conf, and logs.
© Copyright IBM Corporation 2011.
6
To Set Up IIS 7 •
Unzip the downloaded Tomcat Connectors to the bin folder you created at the following location: C:\Inetpub\Jakarta\bin
•
Within the bin folder, create the isapi_redirect.properties file with an editor like Notepad or WordPad. This file tells the .dll where to look for the other properties files that are needed for the redirect. A sample of the isapi_redirect.properties file content is below: extension_uri=/Jakarta/isapi_redirect.dll log_file=C:\Inetpub\Jakarta\logs\iis_redirect.log log_level=debug worker_file=C:\Inetpub\Jakarta\conf\worker.properties worker_mount_file=C:\Inetpub\Jakarta\conf\uriworkermap.properties
•
Change directories to the conf folder at C:\Inetpub\Jakarta\conf and create the uriworkermap.properties file. A sample of the uriworkermap.properties file content is below: /*=default
•
Create the worker.properties file at the following location: C:\Inetpub\Jakarta\conf Set the property worker.default.host to the address of your application. A sample of the worker.properties file content is below:
•
# Define path of .properties files and jdk # Define workers using ajp13 worker.list=default worker.default.type=ajp13 worker.default.host=10.0.1.23 worker.default.port=8009 worker.default.socket_keepalive=1
•
Go to Server Manager > Roles > Web Server (IIS). Confirm that the following roles are installed: ISAPI Extensions ISAPI Filters Basic Authentication Windows Authentication
•
After the folder structure has been created and configured and the needed roles are added to the Web Server, open IIS and double-click on ISAPI and CGI Restrictions.
•
Under Actions, click Add.
© Copyright IBM Corporation 2011.
7
To Set Up IIS 7 •
On the Edit ISAPI or CGI Restriction window, enter the path to the ISAPI_REDIRECT.DLL file and a description and select the check box for Allow extension path to execute and click OK.
•
Go to Default Web Site and double-click on ISAPI Filters.
•
Under Actions, click Add.
•
On the Add ISAPI Filter window, enter a name for the filter and the path to the ISAPI_REDIRECT.DLL file and click OK.
•
Go to Default Web Site and double-click on Add Virtual Directory.
•
On the Add Virtual Directory window, enter “jakarta" into the Alias field and the path to the DLL file (C:\inetpub\jakarta\bin) and click Connect as….
•
On the Connect As window, choose Specific user and click the Set… button.
•
On the Set Credentials window, enter an administrator account user name and password and click OK.
•
On the Add Virtual Directory window, click the Test Settings… button.
•
The Test Connection window will open with the test results. Click the Close button.
•
On the Add Virtual Directory window, click OK. You will now see the virtual directory under the Default Web Site.
•
Click on the virtual directory and then double-click Handler Mappings.
•
Under Actions, click Add Module Mapping….
•
On the Add Module Mapping window, enter *.dll for the Request path; select IsapiModule for the Module; enter the path to the isapi_redirect.dll file for the Executable; enter jakarta for the Name; and click OK.
•
A window may pop up that asks if you want to allow this ISAPI extension. Click Yes to continue.
•
Right-click on jakarta under Handler Mappings and select Edit Feature Permissions.
•
On the Edit Feature Permissions window, the Read, Script, and Execute permissions will be checked. Click OK.
© Copyright IBM Corporation 2011.
8
To Set Up IIS 7 •
If you are not using SSO, confirm that Anonymous Authentication is enabled, Basic Authentication is disabled, and Windows Authentication is disabled. If you are using SSO, confirm that Anonymous Authentication is disabled and either Basic Authentication or Windows Authentication is enabled.
•
Right-click on the host and select Stop and then Start to restart the Default Web Site.
•
Test logging into the application to confirm that IIS is now forwarding requests.
Troubleshooting There are many places to check when troubleshooting the Jakarta Connector. If the sign in page will not display, check the following: Troubleshooting the Jakarta Connector Make sure to note down the location set in the .msi installer. The default the installer uses is: C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\ In this document, we change this to C:\Inetpub\Jakarta. Make sure the worker.properties file is in the correct config folder where the Jakarta Isapi Redirector is installed. •
Double check all the settings in: C:\Inetpub\Jakarta\conf\workers.properties The workers.properties file contains the configuration of the application server. C:\Inetpub\Jakarta\conf\uriworkermap.properties
The uriworkermap.properties file contains the mapping from the Web root context directory to mount to the application server. We use the root / directory in this chapter. •
The registry contains keys for the isapi_redirect.dll, located at: HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0
This key is installed by the .msi installer. The worker_file key should point to the workers.properties file. Make sure the whole path and file name are entered correctly. The worker_mount_file points to the uriworkermap.properties. Make sure the whole path and file name are entered correctly.
© Copyright IBM Corporation 2011.
9
Troubleshooting the Jakarta Connector The isapi_redirect.dll will need permissions from the Web Service Extensions. Check the status column in the All Unknown ISAPI Extensions – it should display Allowed. •
Make sure the application server can be reached from the IIS server on port 8009. To test this, click Start > Run, and enter: telnet where is the hostname or IP address of the application server and is the AJP Port (the default is 8009).
The screen should go blank. If it returns an error in 10 seconds, the Web server cannot connect to the application server. Consult your network administrator if a timeout occurs. If you configure the Jakarta virtual directory to run under a different Application Pool to its parent Web site, any requests to that directory will fail and you will see a 403 18 error in the IIS log files.
© Copyright IBM Corporation 2011.
10
3. Setting Up SSO with IIS Configuring IBM TRIRIGA and IIS After configuring IIS to pass Web requests to JBoss, the next step is to set up SSO. Follow the steps below to set up SSO: To Configure IBM TRIRIGA and IIS •
On the application server, modify TRIRIGAWEB.properties. This file should be located in the Tririga/config folder.
•
Set the following attributes: SSO=Y SSO_REMOTE_USER=Y SSO_REMOVE_DOMAIN_NAME=Y SSO_REQUEST_ATTRIBUTE_NAME=sm_user
Note – If the Active Directory contains usernames with inconsistent cases (for example, if IBM TRIRIGA users have been entered in lower case, and users in Active Directory are in mixed cases), use the following setting to turn off the case sensitive check upon login: USERNAME_CASE_SENSITIVE=N
•
After applying the above settings in TRIRIGAWEB.properties, restart the application server to use the new settings.
•
On the IIS server, right-click My Computer and select Manage.
•
Expand Services and Applications. Select and expand Internet Information Services (IIS) Manager.
•
Under IIS, expand Web Sites.
•
Right-click Default Web Site. Select Properties.
•
In the Default Web Site Properties panel, select the Directory Security tab. In Authentication and access control, click Edit.
•
In the Authentication Methods panel, uncheck the box next to Enable anonymous access.
© Copyright IBM Corporation 2011.
11
To Configure IBM TRIRIGA and IIS •
Check one of the boxes next to: Integrated Windows authentication Digest authentication for Windows domain servers Basic authentication (password is sent in clear text)
Note – If you do not know which one to set, do not choose all three. Try checking one at a time, restarting IIS after the change, and testing to see if the setting works correctly. The correct setting depends on your company’s security setup.
•
Enter the domain name in Default Domain and Realm. Which fields are available depends on the check boxes selected in Authenticated access.
•
Click OK.
•
Click OK to override the AuthFlags property for the jakarta Child Node.
•
Restart IIS and make sure JBoss has been restarted.
•
Make sure you have a login within IBM TRIRIGA that matches your domain login. For example, if your domain login is john.doe, the user name in the profile of the IBM TRIRIGA Employee record should be john.doe.
•
Note – Logins are case sensitive. Some logins in Active Directory are stored in mixed case.
When ready, open your browser to http:/// It should take you directly to IBM TRIRIGA.
•
Some Java Applets will prompt for the Windows user name and password. This is a known security issue with the Java Plugin and IIS.
Affected applets may include: Brava! Document Viewer, Gantt, Association Viewer, and Workflow Expression Editor. Simply enter the SSO user name and password again to gain access to these applets.
Troubleshooting If you are having an issue with automatically logging in, check the following:
© Copyright IBM Corporation 2011.
12
Troubleshooting Automatic Log In •
If you see the error Invalid User name or Password, make sure the SSO settings in the TRIRIGAWEB.properties have been set and JBoss has been restarted.
•
The user name is case sensitive within IBM TRIRIGA. To see the actual user name passed to IBM TRIRIGA via IIS, point your browser to http://
