Configuring SSO for TRIRIGA® on WebSphere Liberty with IIS and AD

There are several steps for configuring single sign-on (SSO) with WebSphere Application Server Liberty, Microsoft Internet Information Services (IIS), and Microsoft Active Directory (AD).

Contents

I. Configuring WebSphere Liberty property trustedSensitiveHeaderOrigin

There was a change on WebSphere Liberty 19.0.0.4 that added a new configuration property named trustedSensitiveHeaderOrigin.

For more details, see Configuring WebSphere Liberty section in Potential WebSphere Application Server problems when deployed behind a WebSphere-aware proxy server support page.

On WebSphere Liberty, trustedSensitiveHeaderOrigin is configured as a HttpDispatcher custom property. This property has a default value of "none", which means that a subset of WebSphere-specific HTTP headers will not be trusted from any host. The property also accepts value a of "*" (all), or a comma-separated list of IP addresses. For a secure deployment in which proxy servers are used, the trustedSensitiveHeaderOrigin property should be configured with a comma-separated list of IP addresses corresponding to those of any WebSphere-aware proxy servers in front of the WebSphere server.

Alternatively, to enable the original unsecured behavior, set trustedSensitiveHeaderOrigin="*", which will direct the WebSphere server to trust all headers sent from any host or proxy. This value must only be used for testing, or if the WebSphere server is isolated from external connections.

For WebSphere Liberty servers, add the following line to the server.xml:

<httpDispatcher trustedSensitiveHeaderOrigin="<TRUSTED_PROXY_IP_ADDRESS>"/>

Replace <TRUSTED_PROXY_IP_ADDRESS> with the IP of the web server machine where the WebSphere plug-in is installed.

See reference: HTTP Dispatcher (httpDispatcher)

II. Configuring IIS to pass web requests to WebSphere Liberty

About this task

If you are using an already installed web server plug-in on the web server, reconfigure it to use the web server plug-in by using the following procedure.

Note: If the web server plug-in is not installed, then install it, but do not use the following procedure since it is completed automatically during web server plug-in installation. You need to complete the steps below only if you are reconfiguring IIS Version 8.x to use an existing web server plug-in.

You can create a web server configuration beforehand by using the WebSphere Customization Toolbox. The configuration will be installed to C:\Program Files (x86)\IBM\WebSphere\Plugins\config\webserver1. When you are prompted for the web server details, point to the URL by using the remote installation.

Procedure

  1. On the Server Manager screen, click Tools > Internet Information Services (IIS) Manager. This action starts the IIS application, and creates a new virtual directory for the website instance that you intend to use with WebSphere Liberty. These instructions assume that you are using the default website.
  2. Expand the tree until you see Default Web Site.
  3. Right-click Default Web Site and select Add Virtual Directory to create the directory with a default installation.
  4. On the Virtual Directory Alias window, enter sePlugins in the Alias field.
  5. In the Physical Path field of the Web Site Content Directory window, browse to and select the pluginConfigFolder\bin directory and click OK. For example, select C:\Program Files (x86)\IBM\WebSphere\Plugins\config\webserver1\bin.
  6. Click Test Settings. If the settings test fails, then either change the permissions of the physical directory, or select Connect As, and let IIS connect as a Windows user account that has authority to files in that physical path.
    Attention: When you click Test Settings, you might encounter the following warning message if you use the default Pass-thru authentication setting: "Cannot verify access to path". For more information, see the Microsoft documentation on this subject.
  7. Click OK to add the sePlugins virtual directory to your default website.
  8. In the navigation tree, select the sePlugins virtual directory that you created.
  9. On the Features panel, double-click Handler Mappings, and then click Edit Feature Permissions on the Actions panel.
  10. Select a resource.
  11. Select Script and Execute, if they are not already selected then click OK.
  12. Manually copy the plug-in binaries file, iisWASPlugin_http.dll, to the plugins_root\bin\ directory. For example, copy the plug-in binary files to the C:\Program Files\IBM\WebSphere\Plugins\bin\ directory.
  13. Return to the IIS Manager window, and expand the Web Sites folder in the left-hand navigation tree of that window.
  14. Select Default Web Site in the navigation tree.
  15. Add the Internet Services Application Programming Interface (ISAPI) filter into the IIS configuration.
  16. On the Default Web Site Properties panel, complete the following steps.
    1. Double-click the ISAPI Filters tab.
    2. Click to open the Add/Edit Filter Properties dialog.
    3. Enter iisWASPlugin in the Filter name field.
    4. Click Browse to select the plug-in file, iisWASPlugin_http.dll, located in the root\config\webserverName\bin directory.
    5. Click OK to close the Add/Edit Filter Properties dialog.
    6. An sePlugins filter is automatically created here and on the server node. They can both be removed.
  17. In the navigation tree, select the top level server node.
  18. On the Features panel, double-click ISAPI and CGI Restrictions, and then, on the Actions panel, click Add.
  19. To determine the value to specify for the ISAPI or CGI Path property, browse to and select the same plug-in file that you selected in the previous step. For example, root\config\webserverName\bin\iisWASPlugin_http.dll.
  20. Enter WASPlugin in the Description field, select Allow extension path to execute, and click OK to close the ISAPI and CGI Restrictions dialog.
  21. Set the value in the plugin-cfg.loc file to the location of the configuration file at plugins_root \config\webserver_name\plugin-cfg.xml.
    • The default location of plugin-cfg.loc is C:\Program Files\IBM\WebSphere\Plugins\bin\IIS_webserverName. You can also create the file manually in a text editor. The only item that the plugin-cfg.loc file contains is the path to the plugin-cfg.xml file. For example, C:\Program Files\IBM\WebSphere\Plugins\config\webserverName\plugin-cfg.xml.
    • The default location of plugin-cfg.xml is C:\Program Files\IBM\WebSphere\Plugins\config\IIS_webserver1\plugin-cfg.xml. The location varies depending on how you have configured your system. If the web server and WebSphere Liberty are on separate machines, you have a remote installation.
    • If the web server and WebSphere Liberty are on the same machine, then you have a local installation, and the correct location of the configuration file might be set. For example, C:\IBM\WebSphere\Plugins\config\webserver1\plugin-cfg.xml.
    • If the two servers are on the same machine, and the application server is federated, you have a local distributed installation. For example, C:\IBM\WebSphere\AppServer\profiles\custom01\config\cells\dmgrcell\nodes\managed_node\servers \webserver1\plugin-cfg.xml.
  22. Generate a new version of plugin-cfg.xml from your Liberty application server. As the user that is running Liberty (may be Administrator) go to the Java home directory that Liberty uses, and run: jconsole. Connect to your server then click the MBeans tab. Under the WebSphere section, locate the com.ibm.ws.jmx.mbeans.generatePluginConfig MBean generateDefaultPluginConfig operation to generate the plugin-cfg.xml file, or call thegeneratePluginConfig operation to customize installation root directory and server name before you generate the plugin-cfg.xml file.
  23. You will need to copy the plugin-cfg.xml file to the web server, replacing the existing plugin-cfg.xml file configured for IIS to read. Here is an example of the generated plugin-cfg.xml: 
    <?xml version="1.0" encoding="UTF-8"?><!--HTTP server plugin config file for defaultServer generated on 2015.03.02 
at 20:29:36 GMT-->
<Config ASDisableNagle="false" AcceptAllContent="false" AppServerPortPreference="HostHeader" ChunkedResponse="false" 
FIPSEnable="false" IISDisableNagle="false" IISPluginPriority="High" IgnoreDNSFailures="false" RefreshInterval="60" 
ResponseChunkSize="64" SSLConsolidate="false" TrustedProxyEnable="false" VHostMatchingCompat="false">
   <Log LogLevel="Error" Name=".\logs\webserver1\http_plugin.log"/>
   <Property Name="ESIEnable" Value="true"/>
   <Property Name="ESIMaxCacheSize" Value="1024"/>
   <Property Name="ESIInvalidationMonitor" Value="false"/>
   <Property Name="ESIEnableToPassCookies" Value="false"/>
   <Property Name="PluginInstallRoot" Value="."/>
<!-- Configuration generated using httpEndpointRef=defaultHttpEndpoint-->
<!-- The default_host contained only aliases for endpoint defaultHttpEndpoint.
     The generated VirtualHostGroup will contain only configured web server ports:
        webserverPort=80
        webserverSecurePort=443 -->
   <VirtualHostGroup Name="default_host">
      <VirtualHost Name="*:81"/>
   </VirtualHostGroup>
   <ServerCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true" LoadBalance="Round Robin" 
Name="defaultServer_default_node_Cluster" PostBufferSize="0" PostSizeLimit="-1" RemoveSpecialHeaders="true" RetryInterval="60">
      <Server CloneID="861158e3-af1e-47fe-b1c4-f21622bbc450" ConnectTimeout="5" ExtendedHandshake="false" MaxConnections="-1" 
Name="default_node_defaultServer" ServerIOTimeout="900" WaitForContinue="false">
         <Transport Hostname="triqaapp11.tivlab.usnv.ibm.com" Port="8001" Protocol="http"/>
         <Transport Hostname="triqaapp11.tivlab.usnv.ibm.com" Port="8443" Protocol="https">
            <Property Name="keyring" Value="keyring.kdb"/>
            <Property Name="stashfile" Value="keyring.sth"/>
            <Property Name="certLabel" Value="LibertyCert"/>
         </Transport>
      </Server>
      <PrimaryServers>
         <Server Name="default_node_defaultServer"/>
      </PrimaryServers>
   </ServerCluster>
   <UriGroup Name="default_host_defaultServer_default_node_Cluster_URIs">
      <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/*"/>
   </UriGroup>
   <Route ServerCluster="defaultServer_default_node_Cluster" UriGroup="default_host_defaultServer_default_node_Cluster_URIs" 
VirtualHostGroup="default_host"/>
</Config>

III. Configuring SSO with Microsoft IIS

About this task

After configuring IIS to pass web requests to WebSphere Liberty, the next step is to set up SSO.

Procedure

  1. On the application server, set the following attributes in the TRIRIGAWEB.properties file. This file should be located in the Tririga/config folder. 
    SSO=Y
SSO_REMOTE_USER=N
SSO_REMOVE_DOMAIN_NAME=Y
SSO_REQUEST_ATTRIBUTE_NAME=$WSRU   
USERNAME_CASE_SENSITIVE=N

    If AD contains usernames with inconsistent cases (for example, if TRIRIGA users have been entered in lower case, and users in AD are in mixed cases), use the following setting to turn off the case-sensitive check upon login:

    USERNAME_CASE_SENSITIVE=N

    If you want to force users to log in through SSO, you must prevent them from using the default login page. Provide an alternative login page that does not contain a username, password, or login button. Use the following settings to specify the alternative login page and directory:

    ALTERNATE_INDEX_HTML=<indexFileName.html>
ALTERNATE_RESOURCE_DIRECTORY=/<pathToTRIRIGA>/userfiles/alt
  2. Restart the application server to use the new settings.
  3. On the IIS server, right-click My Computer and select Manage.
  4. Expand Services and Applications. Select and expand Internet Information Services (IIS) Manager.
  5. Under IIS, expand Web Sites.
  6. Right-click Default Web Site and select Properties.
  7. In the Default Web Site Properties panel, select the Directory Security tab. In Authentication and access control, click Edit.
  8. In the Authentication Methods panel, uncheck the box next to Enable anonymous access.
  9. Select the type of authentication. 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.
    • Integrated Windows authentication
    • Digest authentication for Windows domain servers
    • Basic authentication (password is sent in clear text)
  10. Enter the domain name in Default Domain and Realm. The fields that are available depend on the check boxes selected in Authenticated access.
  11. Click OK.
  12. Restart IIS and make sure that the application server has been restarted.
  13. Make sure you have a login within TRIRIGA that matches your domain login. If your domain login is john.doe, the user name in the profile of the TRIRIGA Employee record should be john.doe.
    Note: Logins are case-sensitive. Some logins in Active Directory are stored in mixed case.
  14. Open your browser to http://<<webserver>>/. It should take you directly to TRIRIGA.

IV. Troubleshooting IIS and Maximum File Upload Size

About this task

If you have MAXIMUM_UPLOAD_FILE_SIZE_MEGABYTES property set to a large value (for example, 50 MB) in the TRIRIGAWEB.properties file, but you are still running into problems with uploading large files, Microsoft IIS Web Server's default configuration needs to be changed to allow large files to be uploaded too.

Procedure

  1. Open IIS Admin, click on the server, and then double-click Configuration Editor.
  2. After that opens, select system.webServer/security/requestFiltering from the dropdown at the top of the window.
  3. Expand "requestLimits" and edit the "maxAllowedContentLength" setting to the desired amount.
    Note: The default is 30000000 bytes, which is roughly 28 MB. In this example, the value was changed to 90000000 bytes, which is roughly 84 MB. IIS has a maximum size of 2 GB, which is 2147483648 bytes.