IBM Tivoli Access Manager: WebSEAL Kerberos Junctions

Configuring an environment for WebSEAL Kerberos Junctions

To successfully enable a single-sign-on from WebSEAL to a Kerberos enabled Web Server, a number of interlocking components need to be configured correctly. The configuration of this environment is complex and requires careful planning and execution. This article highlights the steps necessary to configure a typical environment for WebSEAL Kerberos junctions, and provides tips for testing and debugging configuration components.

Share:

Scott A. Exton (scotte@au1.ibm.com), Development Team Lead - IBM Tivoli Access Manager Plug-in for Web Servers, IBM

Scott ExtonScott Exton is a development lead for the IBM Tivoli Access Manager product. He is currently responsible for the development of the Plug-in for Web Servers, and Session Management Server components. He joined IBM in Gold Coast Australia as a software engineer in 1997 and has been working on the IBM Tivoli Access Manager product since then. His undergraduate degree is in Business Computing from the Queensland University of Technology.



Philip Nye (philip.nye@au1.ibm.com), Software Development Engineer, IBM

Philip NyePhilip Nye is a Software Development Engineer at the Gold Coast Tivoli Lab. In his time at IBM he has worked on the development of Tivoli Access Manager e-business integration components and developed for Tivoli Access Manager for Operating Systems, and is now working to develop stronger integration between Tivoli Products and Microsoft Office SharePoint. His undergraduate degrees are a Bachelor of Engineering in Software Engineering and a Bachelor of Business Management from the University of Queensland.



18 December 2008 (First published 06 August 2008)

Overview

IBM® Tivoli® Access Manager (TAM) v6.1 introduced the concept of Kerberos junctions for WebSEAL. A Kerberos junction can be used to perform a single-sign-on to a Web server that has been enabled for Kerberos authentication. The Kerberos STS module (introduced in Tivoili Federated Identity Manager (TFIM) v6.2) manages the generation of the Kerberos token, which is used to perform the SSO. The identity that is used during the SSO operation can be that of the established TAM user identity, or it can be another mapped user identity. This identity mapping is controlled by TFIM.

TFIM uses the Microsoft® extensions to Kerberos to generate a valid Kerberos token based on a supplied user identity. These extensions come in two parts:

  • Protocol transition (or S4U2Self) allows impersonation to take place based on a supplied user identity;
  • Constrained delegation (or S4U2Proxy) allows a Kerberos service ticket to be created for consumption by a separate identity.

When combined, these two extensions provide a means of creating a Kerberos service ticket on behalf of another user in order to access a target resource. In other words, the extensions provide TFIM with the capability to create a Kerberos service ticket on behalf of the TAM user, which can be then used to access the junctioned Web server.

Figure 1 shows the typical sequence of steps involved in performing a Kerberos single-sign-on after the TAM identity has been established.

Figure 1. SSO sequence
SSO Sequence

This article provides step-by-step details on the configuration of a typical customer user environment for Kerberos single-sign-on (SSO). The environment deploys TFIM in an IBM WebSphere® clustered environment, although the majority of the article also holds true if TFIM is running within a standalone WebSphere Application Server (WAS). Figure 2 depicts the architecture of the environment, which is referenced throughout this article.

Figure 2. Environment overview
Environment Overview

TFIM platform

The TFIM Kerberos STS module is only available on the Windows 2003 platform and above due to the fact that it utilizes the Microsoft extensions to Kerberos, which are only supported on Windows 2003 and newer operating systems. When running Windows Server 2003, also ensure that Service Pack 2 is installed because of a memory leak as described at:
http://support.microsoft.com/kb/907524.

This article does not cover the configuration of the entire environment. In particular, it assumes that the configurations of the following entities have already been completed:

  • Tivoli Access Manager v6.1:
    • User Registry (any of the supported registries)
    • TAM Policy Server
    • WebSEAL (initial configuration)
  • Tivoli Federated Identity Manager v6.2:
    • Deployed to a WAS cluster
    • A TFIM domain has been configured and the runtime has been deployed to the domain.
  • Microsoft:
    • Domain Controller - including Active Directory and the Microsoft Support Tools
    • IIS 6.0, or IIS 7.0 - enabled for Kerberos authentication

This article will also outline the difference between configuring against an IIS 6.0 webserver running on Windows Server 2003 and IIS 7.0 running on Windows Server 2008 where possible.

This article will concentrate on the aspects of the environment which must be customized in order to perform a Kerberos single sign-on from WebSEAL. In particular, this will include:

  1. Configuring the IIS instance to run as an Active Directory user with an assigned Service Principle Name.
  2. Enabling the WebSphere - TFIM instance to generate a delegated Kerberos service ticket.
  3. Configuring the TFIM Kerberos STS module and TFIM trust chain.
  4. Configuring the TAMeb Kerberos junction to the IIS server to use the generated delegated Kerberos ticket.

This article will conclude with a brief troubleshooting section which describes how to troubleshoot your environment if the Kerberos single sign-on fails.


Step 1: Configuring IIS

Time Synchronization

Kerberos tickets rely on embedded time stamps to expire old tickets. For this reason it is important to ensure that the clocks on all machines in the environment are synchronized.

In order for constrained delegation to operate correctly the target service (i.e. IIS) must be running as an Active Directory (AD) user which has an assigned Service Principal Name (SPN) and is configured to run as a Kerberos service. To run IIS as an AD user, complete the following steps:

  1. Create and initialize the AD user:
    1. On the domain controller, select Active Directory Users and Computers, from the Administrative Tools section of the Start Menu. Create a new user whose password never expires.
      Figure 3. IIS user creation
      IIS User Creation
    2. On the domain controller, prepare the new user so that it can execute as a Kerberos service. This is done using the ktpass command line utility which is provided as a part of the Windows support tools. Once the SPN has been set for the user, the login name will also be changed to reflect the SPN. The syntax for ktpass is shown in Listing 1.
      Listing 1. ktpass command
      ktpass -princ HTTP/<IIS Server Name>.<DNS domain name>@<AD DOMAIN NAME> \
              -mapuser <IIS User Name> -mapOp set
      Figure 4 shows an example command and its output.
      Figure 4. Setting the user SPN
      Setting the user SPN
    3. Windows Server 2003 / IIS 6.0: On the IIS system, the AD user must be made a member of the local IIS_WPG group. To do this, select Computer Management from the Administrative Tools section of the Start Menu, or if the machine is a Domain Controller, select Active Directory Users and Groups and under the Builtin user list locate the IIS_WPG group and then add the new AD user to this group.
      Figure 5. IIS_WPG group
      Adding the user to the IIS_WPG groupWindows Server 2008 / IIS 7.0: On the IIS system the AD user must be made a member of the local IIS_IUSRS group. To do this, select Computer Management from the Administrative Tools section of the Start Menu, or if the machine is a Domain Controller, select Active Directory Users and Groups and under the Builtin user list locate the IIS_IUSRS group and then add the new AD user to this group.
      Figure 6. IIS_IUSRS group
      Adding the user to the IIS_IUSRS group
  2. By default the security policy of the machine will not allow an AD user to execute a local service. This needs to be changed so that the new AD user is allowed to execute IIS as a service. Select Local Security Policy from the Administrative Tools section of the Start Menu, then extend the "Log on as a service" local policy to include the new AD user.
    Figure 7. Security policy
    Modifying the local security policy
  3. Configure the IIS application pool to execute as the AD user:
    1. On the IIS system use the IIS Manager to change the identity used to execute requests.
      Note: When using backend web applications that require additional specific privileges beyond IIS, please refer to your product documentation when changing the IIS service user account. Microsoft Office SharePoint is one such example where it is advised to modify the service user through the SharePoint Central Administration Console.

      On Windows Server 2003 / IIS 6.0: Do this by editing the properties for the target Application Pool.
      Figure 8. IIS 6.0 application pool identity
      IIS 6.0 Application Pool IdentityOn Windows Server 2008 / IIS 7.0: Do this by modifying the identity in the advanced settings dialog.
      Figure 9. IIS 7.0 application pool identity
      IIS 7.0 Application Pool Identity
    2. On the IIS system use the IIS Manager to recycle the target application pool so that the changes made in the previous step take effect.
      On Windows Server 2003 / IIS 6.0: This can be done by "right-clicking" the application pool, as detailed in Figure 10.
      Figure 10. IIS 6.0 Recycle IIS application pool
      Recycle IIS Application PoolOn Windows Server 2008 / IIS 7.0: This can be done by selecting "Recycle" in the application pool Actions pane, as detailed in Figure 11.
      Figure 11. IIS 7.0 Recycle IIS application pool
      Recycle IIS Application Pool
  4. Open a Web browser and access the Web server to ensure that it is still functioning correctly. The process list, available from the Windows Task Manager, should also be examined to ensure that each of the applicable w3wp.exe processes are being executed as the newly created AD user as shown in Figure 12.
    Figure 12. IIS validation
    IIS ValidationNote: The IIS w3wp.exe service for the application may not appear in the process list until the site has been accessed.

    If you are running on Windows Server 2003 with IIS 6.0, IIS should now be configured, please continue to the Step 2: WebSphere TFIM Configuration.
    If you are running on Windows Server 2008 with IIS 7.0 there are some additional steps required in order to support the WebSEAL Kerberos Junction configuration.
  5. Windows Server 2008 / IIS 7.0: Under the Authentication option for each site being junctioned to, kernel based Kerberos authentication must be disabled. This is due to the way WebSEAL contacts the IIS webserver with the Kerberos credentials in the initial request and a limitation in the Kernel based authentication. This can be disabled by "right-clicking" Windows Authentication on the sites authentication page as shown in Figure 13.
    Figure 13. Kerberos advanced settings
    Kerberos Advanced Settings
    Uncheck the box to "Enable Kernel mode Authentication" as shown in Figure 14.
    Figure 14. Kerberos advanced settings dialog
    Kerberos Advanced Settings Dialog
    On the authentication screen, also ensure that ASP.NET Impersonation is enabled as shown in the top of Figure 13.
    When impersonation and Kerberos are used together IIS 7.0 generates a warning that prevents the website from being displayed as shown in Figure 15.
    Figure 15. Integrated managed pipeline error.
    Integrated Managed Pipeline error
    This error must be suppressed by adding the bold XML shown in Listing 2 to the applicationHost.config file on the IIS host. The default location for this file is: C:\Windows\System32\inetsrv\config\. Alternatively it can be added to the web.config file for each applicable web application however the applicationHost.config file will always override this. For more information on this topic see: http://learn.iis.net/page.aspx/124/.
    Listing 2. Application config
    <location path="Default Web Site">
        <system.webServer>
            <security>
                <authentication>
                    <anonymousAuthentication enabled="false" />
                    <windowsAuthentication enabled="true" useKernelMode="false" />
                </authentication>
            </security>
            <validation validateIntegratedModeConfiguration="false" />
        </system.webServer>
    </location>

Also in the <windowsAuthentication> block ensure that if the attribute useAppPoolCredentials exists it is not set to "true".

Once these changes have been made, recycle the application pool as shown in figure 11.


Step 2: WebSphere - TFIM user configuration

Node Agent

If using a WAS stand alone server rather than WAS ND, the application server process itself (rather than the node agent) must be run under an AD account. In WAS ND, the node agent is responsible for starting and stopping the application server processes, and they inherit the identity of the parent process. This is why the nodeagent, in a WAS ND environment, is modified to run using an active directory account.

The WebSphere node agent that hosts the Tivoli Federated Identity Manager runtime needs to run under a special account in Active Directory. This is required so that it can be given permission to obtain Kerberos tickets for other users and a constrained set of targets. You need to create the account, set the appropriate options, and modify the WebSphere service to use the account before your Kerberos delegation trust chain can work. The following instructions describe how to complete this task.

  1. On the domain controller, ensure the domain functional level is set to Windows Server 2003. This step is required in order to get the Windows Kerberos constrained delegation to work. Select Active Directory Users and Computers from the Administrative Tools section of the Start Menu, then right click on the domain and select Properties in order to see what level the Domain Controller is running, an example of this screen is shown in Figure 16. If this is older than 2003, the Kerberos Constrained delegation will not work. To upgrade, right click on the domain and select Raise Domain Functional Level.
    Figure 16. Domain functional level
    Domain Functional Level
  2. Create and initialize the AD user:
    1. On the domain controller, select Active Directory Users and Computers, from the Administrative Tools section of the Start Menu. Create a new user configured with a password that never expires.
      Figure 17. TFIM user creation
      TFIM User Creation
    2. On the domain controller set the SPN for the new AD user. This is done using the setspn command line utility, which is provided as a part of the Windows support tools. The syntax for setspn is shown in Listing 3.
      Listing 3. setspn command
      setspn -A tfim/<tfim user> <tfim user>
      Figure 18 shows an example command and its output.
      Figure 18. Setting the user SPN
      Setting the user SPN
    3. On the TFIM server (or on each server if they are a part of a cluster), make the AD TFIM user a member of the local Administrators group. Do this by selecting Computer Management, from the Administrative Tools section of the Start Menu. Locate the Administrators group under Local Users and Groups -> Groups and then add the new AD user to that group as shown in Figure 19.

      Note: Some guides suggest the user should be a member of the Domain Admins group, this is not necessary as long as the TFIM user is a local computer administrator.
      Figure 19. Administrators group
      Adding TFIM user to the Local Administrators group
    4. The AD user must also be modified so that it is trusted to delegate for the IIS service. To do this, select Active Directory Users and Computers, from the Administrative Tools section of the Start Menu on the domain controller. Open the properties for the new AD user, select the Delegation tab and then enable delegation to the IIS user that was created in Figure 4 of this article.

      Note: When searching for the service, be sure to search by the IIS username and not the server hostname, and select the HTTP service that is shown in FULL CAPS. Once completed the TFIM users Properties - Delegation tab should look similar to the one shown in Figure 20.
      Figure 20. Permission to delegate
      Permission to Delegate
    5. The AD user must also be added to the Windows Authorization Access Groups object. Select Active Directory Users and Computers, from the Administrative Tools section of the Start Menu on the domain controller. Select the Builtin object and then modify the properties of the Windows Authorization Access Groups object, making the new AD user a member of the group as shown in Figure 21.
      Figure 21. Windows authorization access groups
      Windows Authorization Access Groups
    6. By default the security policy of the machine will not allow an AD user to execute a local service. Change this so that the new AD user is allowed to execute WebSphere as a service. Update the policy on the WAS server by selecting Local Security Policy, from the Administrative Tools section of the Start Menu. The "Log on as a service" local policy needs to be modified to include the new AD user. For a clustered environment this step must be repeated on all machines hosting a node member which runs the Tivoli Federated Identity Manager runtime. An example is shown in Figure 22.
      Figure 22. TFIM User - Log on as a service
      Modify the Local Security Settings to allow the TFIM user to act as a service.
    7. The new AD user also needs to be given permission on the WAS server, to act as a part of the operating system. Update the policy by selecting Local Security Policy, from the Administrative Tools section of the Start Menu. The "Act as a part of the operating system" local policy, for the User Rights Assignment entry needs to be extended to include the new AD user. For a clustered environment this step must be repeated on all machines hosting a node member which runs the Tivoli Federated Identity Manager runtime. An example is shown in Figure 23.
      Figure 23. TFIM User - Act as part of the operating System
      Modifying the WAS local security policy
  3. The WebSphere node agent service must then be configured to run as a process under the AD principal created above. The following steps must be repeated on all machines hosting a node member which runs the Tivoli Federated Identity Manager runtime.
    1. Enable the WebSphere process to run as a Windows service by executing the wasservice command which is located in the WebSphere bin directory. An example command and its output is shown in Figure 24.
      Note: This may have been run as part of the install process, and is only necessary if the service is not listed in the Services pane of the operating system as shown in the next step.
      Figure 24. Enable WAS Service
      Running WAS as a service
    2. The WebSphere node agent service needs to be modified to run as the new TFIM AD user. This is achieved using the Services control panel, which is available from the Administrative Tools sections of the Start Menu, and modifying the properties of the IBM WebSphere Application Server Service. The username to run as is located on the Log On tab, an example is shown in Figure 25
      Figure 25. WAS service user
      Running WAS as the AD user
    3. If WebSphere is running at this stage, it must be restarted to reflect the changes to the Service properties. This can be achieved by executing the stopnode and startnode commands which are located in the WebSphere bin directory. An example of these commands and there output is shown in Figure 26
      Figure 26. WAS node restart
      Restarting the WAS node agent
  4. Check to ensure that the WAS service is running as the new AD user. The process list containing this information, which is available from the Windows Task Manager, should be examined to ensure that a java.exe and a WasService.exe process is being executed as the new AD user. As shown in Figure 27
    Figure 27. WAS runtime user validation
    WAS Validation

Step 3: TFIM trust chain

A TFIM trust chain must be set up so that TFIM is able to convert a supplied IV-Cred into a Kerberos token. A trust chain configuration comprises of a number of TFIM modules which are executed in sequence. The minimal trust chain required for a WebSEAL Kerberos junction consists of an IVCred Token module (used to extract the user identity information from the IV Credential), followed by a Kerberos Delegation module (used to generate the Kerberos token). The default module instance for the IVCred Token module may be used in the trust chain, but a new Keberos Delegation module instance must be created and used. An optional mapping module may be inserted between the IVCred Token module and the Kerberos Delegation module if you wish to perform identity mapping between the TAM user ID and the AD identity contained within the generated Kerberos token.

Figure 28. Trust chain
Trust Chain
  1. Create an instance of the Kerberos Delegation STS module by invoking the Create wizard on the WebSphere console:
    1. Select Tivoli Federated Identity Manager to expand it.
    2. Then select Configure Trust Service to expand it.
    3. Then select Module Instances.
    4. On the displayed Module Instances Page, Click the Create button.
    The configuration information for the new 'Kerberos Delegation STS Module' instance is performed by a Wizard. On the first page (figure 29) you select the com.tivoli.am.fim.trustserver.sts.modules.KerberosDelegationSTSModule Module type. Click Next.
    Figure 29. Kerberos Delegation STS module Wizard Step 1.
    Kerberos Delegation STS module Wizard Step 1.
    On the second page (figure 30) name the module, such as Kerberos Token (remember this name as we will use it in the construction of the trust chain) and provide a description similar to: Module which is used to create Kerberos Token. Click Next.
    Figure 30. Kerberos Delegation STS module Wizard Step 2.
    Kerberos Delegation STS module Wizard Step 2.
    On the third page (figure 31) we can specify the maximum size of our credential cache, the default is fine here. Click Finish. Note: This credential cache is a LRU collection of Kerberos Local Security Authority (LSA) login handles. Each time a new user ticket is required, TFIM uses a login handle, and this cache maintains a list of existing logins to speed the generation of successive ticket requests.
    Figure 31. Kerberos Delegation STS module Wizard Step 3.
    Kerberos Delegation STS module Wizard Step 3.
    The Kerberos Delegation module is now configured.
  2. The actual trust chain which will be invoked to generate the Kerberos token should now be created. As mentioned earlier the minimal trust chain will consist of two modules instances: the default IV Cred Token module instance and the new Kerberos module instance created in the prior step. The IV-Cred Token module instance must be created in "validate" mode, and the Kerberos module instance must be created in "issue" mode. In order for TFIM to correctly select the trust chain which is to be invoked, certain selection criteria are included in the trust chain configuration. Create the trust chain by invoking the Create wizard on the WebSphere console:
    1. Select Tivoli Federated Identity Manager to expand it.
    2. Then select Configure Trust Service to expand it.
    3. Then select Trust Service Chains.
    4. On the displayed Trust Service Chains page, Click the Create button.
    The configuration information for the various wizard steps are depicted in the following figures.

    Note: During the creation of the trust chain a warning will be displayed stating that the module chain does not meet the recommended chain structure. It is safe to just ignore this warning and continue with the creation of the trust chain.

    On the first page of the Wizard, Click next after reading the Introduction.
    Figure 32 shows the second page of the wizard where we are asked to name and describe our trust chain. Name this chain WebSEAL Kerberos Junction and provided a description similar to Trust chain to generate a token for a WebSEAL Kerberos Junction. Click Next.
    Figure 32. Trust Chain Wizard Page 2
    Trust Chain Wizard Part 1
    The importantant fields on the third page of the wizard, shown in Figure 33 include:
    1. The "AppliesTo Address" field which corresponds to the WebSEAL "applies-to" configuration entry. In this example, this corresponds with the full path to the junction. It is possible to use a wild card '*' here if you have multiple junctions to the same machine.
    2. The "AppliesTo Service Name" field which corresponds to the WebSEAL "service-name" configuration entry. The service name contained in the RST sent from WebSEAL will be matched against the second component of the Service Name field (i.e. the one which occurs after the colon). In the example given above the '*' character has been supplied for both components of the Service Name so that all requests with the same address will match.
    3. The "Issuer Address" which should always be set to "amwebrte-sts-client".
    Figure 33. Trust Chain Wizard Page 3
    Trust Chain Wizard Part 2
    Complete the fourth page Figure 34 similar to page 2 of the wizard.
    Figure 34. Trust Chain Wizard Page 4
    Trust Chain Wizard Part 3
    On Page 5, we assemble the two modules for our Trust Chain.
    1. First add a Default IVCred Token Module in Validate Mode.
    2. Secondly add the Kerberos Token module we created earlier in Issue mode.
    Figure 35 shows the result. Click Next. Ignore the warning that is presented, and Click Continue.
    Figure 35. Trust Chain Wizard Page 5
    Trust Chain Wizard Part 4
    On the IVCred Module configuration page, no options are required, as shown in Figure 36.
    Figure 36. Trust Chain Wizard Page 6
    Trust Chain Wizard Part 5
    On the Kerberos Delegation Module configuration page, select the option Add the machine DNS domain as a suffix to the username as shown Figure 37 Click Next.
    Figure 37. Trust Chain Wizard Page 7
    Trust Chain Wizard Part 6
    Review the configuration on the final page, and Click Finish to create the TFIM Kerberos delegation Trust Chain.

TFIM configuration changes

Be sure to load the TFIM configuration changes in order for the new trust chain to take affect. Sometimes a complete restart of the cluster is required in order to apply TFIM configuration changes. If the changes don't appear to take affect after a reload, try restarting your cluster as well.

Once the configuration changes have been loaded into TFIM the new trust chain should be validated to ensure that it can successfully create a Kerberos token. This can be achieved by building up and issuing an RST request to TFIM. In the event of an error the WebSphere stdout log file should be examined for a more complete description of the problem. An example RST request, rst.xml, for a user named testuser has been included with this article. The following example in Listing 4 shows how to issue an RST request using the curl client. If everything has been configured correctly this command should return with an RSTR response which contains a Kerberos token.
Before running the command below, modify the XML such that the <wsa:Address> matches the address provided in the TFIM Trust Chain, and the <wsa:ServiceName> matches the delegated SPN (e.g HTTP/server1.jkhle.com).

Listing 4. Sample curl command
curl --header "soapaction: blah" --data-binary @rst.xml \
    http://<TFIM server>:<TFIM Port>/TrustServerWST13/services/RequestSecurityToken

Result:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope ...>
    <soapenv:Header>
        <ns1:Security ...>
            <ns1:Timestamp>
                <ns1:Created>2008-11-19T01:53:36Z</ns1:Created>
            </ns1:Timestamp>
        </ns1:Security>
    </soapenv:Header>
    <soapenv:Body>
    <wst:RequestSecurityTokenResponseCollection ...>
        <wst:RequestSecurityTokenResponse Context="" ...>
            <wst:TokenType>
                http://docs.oasis-open.org/wss/...
            </wst:TokenType>
            <wsp:AppliesTo ...>
                <wsa:EndpointReference ...>
                    <wsa:Address>
                        http://server2.jkhle.com/iis
                    </wsa:Address>
                    <wsa:ServiceName>
                        :HTTP/server1.jkhle.com
                    </wsa:ServiceName>
                </wsa:EndpointReference>
            </wsp:AppliesTo>
            <wst:RequestedSecurityToken>
                <wss:BinarySecurityToken ...>
                    YIIFqQYJKoZIhvcSAQICAQBuggWYMIIFlKADAgEK6gFw0/z3pi90VY6570BNi1
                    kTyP+3e6Cp7yOpOdqmtNKIZJYkAUWfQ1eaS+B0n9OJgbi5lyNAc1dgDlgI+X2C
                    a7hi4FkXl2x5b/esLl+wVLBFoLgN12XP2oG3UVf2sPEozxlfSn0oiiPcZ488tm
                    GuzOetyQ2p9c2CXL+JgWbR5elPzoLP9LYVpppQlJ9yxw/8IK429ylzRFR8kPuE
                    IHjuBdKpvBBpn7y78xeeRnXg9ydQjVbHIcjmr+ArMrY7fkCrNvcYVQhq7p5CbB
                    SOmSuFw0/z3pi90VY6570BNi1U5f4cTb+Va3DLJZTDyEHUwdeDKk4VlgT4zjjl
                    oBL1SkzIBSnNsny7FWH/sS75TmUv8FUoYGvlPpXqEPAC2hAT43yzdJ8VsN5vlq
                    YbUtXjYPWs27wpMrUHohA7LpuzO7lZ1DJ0OVL9uedsv3+OUWcMDovuPXYFUmpA
                    Y0lNCNo2sotS3IurJ1X5cU28ACrkr8yX2uBVv3ri0nFV6Z/Q0jptheQBleI2d1
                    +CK9pYJNkPM8aGFnqRG45hUxx9nfMdLQ7lY6L1y7vM3ne31E47PpGjG0ulZLXX
                    EXn6pEuvBDoeCWlWN8VKCCVm5wEM4kD4ny92gn9czJjIY4z6hzia5Ct45vMmEz
                    4ZpF7KdnciLX52eVPQvS+grSdMIRtbC/4yp9nWokzP5+pjxR8pmFRXjCpUQ4dQ
                    6xnQX3jgPuYEdDi4rUAHWBI2vCo+7e82xTUCNbXTbdEEM/LsixzOWwBna/I10K
                    13sdKk8shL7ybhSXyyRS0z17SiXdLqTyChhPzYz1Y/uEt6mynZo+qRKRuNPTiy
                    ...
                    4mDLqM59vj4DwGWfxj6nZOCAKzweVGA8Tfm+OSCtbBdLQ7lY6L1y7vM3dLQ7lY
                    ocAAeDdzeFRhHIYWmdc1bFDTMZEIhJGE17ScLw==
                </wss:BinarySecurityToken>
            </wst:RequestedSecurityToken>
            <wst:Lifetime ...>
                <wsu:Expires>2008-11-19T02:03:42Z</wsu:Expires>
            </wst:Lifetime>
        </wst:RequestSecurityTokenResponse>
    </wst:RequestSecurityTokenResponseCollection>
    </soapenv:Body>
</soapenv:Envelope>

Step 4: WebSEAL Kerberos Junction

Now that TFIM has been correctly configured with a Kerberos trust chain, the final step in the configuration is to create the Kerberos enabled junction for WebSEAL. The following steps show how to configure a WebSEAL Kerberos junction.

  1. The configuration for WebSEAL Kerberos junctions is contained within the WebSEAL configuration file. This configuration must be completed before the junction itself can be created. There are two stanzas within the configuration file which must be modified: [tfimsso:<jct-id>] and [tfim-cluster:<cluster>]. The first stanza contains the general configuration details for the Kerberos junction while the second stanza contains the configuration details which are used to connect and communicate with TFIM.

    In a high-availability environment there are two ways to configure load balancing and failover amongst multiple WebSphere Application Servers. The first method is to configure the WebSphere Web Server plug-in with knowledge of all cluster nodes. In this scenario WebSEAL will only ever communicate with a single server which then handles the distribution of requests amongst the various cluster nodes. The second method is to have WebSEAL perform the distribution of requests itself by specifying multiple server URL's in the WebSEAL configuration file.

    Listing 5 shows the configuration for the environment documented in this article. It only includes those configuration entries which have actually been changed from the default WebSEAL template configuration.

    Listing 5. WebSEAL configuration file extract
    [tfimsso:/iis]
    
    #
    # This stanza is used to hold the TFIM single sign-on configuration information
    # for a single junction.
    #
    # For standard junctions the stanza name will be qualified with the name of the
    # junction point (including the leading '/').  An example stanza name might be:
    # [tfimsso:/junction_a]
    #
    # For virtual host junctions the stanza name will be qualified with the
    # virtual host label.  An example stanza name might be:
    # [tfimsso:www.ibm.com]
    #
    
    # The 'applies-to' search criteria used when locating the appropriate STS
    # module within TFIM.  Generally this entry should be of the format:
    # http://<webseal-server>/<junction> (similar to the URL which is used to
    # access the junction).
    applies-to = http://server2.jkhle.com/iis
    
    # The service-name configuration entry will be used:
    #   1. By TFIM when searching for a matching trust chain.  This configuration
    #      entry will be compared against the configured 'AppliesTo' service name
    #      value for each trust chain.  The second field within the 'AppliesTo'
    #      service name configuration entry should be set to either '*' to match
    #      all service names, or it should be set to the value defined by this
    #      configuration item.  Refer to the TFIM documentation for further
    #      details on configuring Trust Chains.
    #   2. As the service principal name of the delegating user when creating the
    #      Kerberos token.  The service principal name can be determined by
    #      executing the Microsoft utility 'setspn', i.e. setspn -L <user>,
    #      where <user> is the identity of the user which the junctioned Web server
    #      is running as.
    service-name = HTTP/server1.jkhle.com
    
    # This boolean value is used to indicate whether a security token should be
    # sent for every HTTP request, or whether WebSEAL should wait for a 401
    # response from the back-end Web server before adding the security token.  This
    # configuration item is used to avoid the unnecessary overhead of generating
    # and adding a security token to every request if the back-end Web server is
    # capable of maintaining user sessions.
    always-send-tokens = true
    
    # The name of the WAS cluster which houses this TFIM service.  There should
    # also be a corresponding [tfim-cluster:<cluster>] stanza which contains the
    # definition of the cluster.
    tfim-cluster-name = jkhle
    
    [tfim-cluster:jkhle]
    
    #
    # This stanza contains definitions for a particular cluster of TFIM
    # servers.
    #
    
    #
    # A specification for the server which is used when communicating with a
    # single TFIM server which is a member of this cluster.  Values for this
    # entry are defined as follows:
    #
    #       {[0-9],}<URL>
    #
    # Where the first digit (if present) represents the priority of the server
    # within the cluster (9 being the highest, 0 being lowest).  If the priority
    # is not specified, a priority of 9 is assumed.  The <URL> can be any
    # well-formed HTTP or HTTPS URL.
    #
    # Multiple server entries can be specified for failover and load balancing
    # purposes.  The complete set of these server entries defines the
    # membership of the cluster for failover and load balancing.
    #
    # server = 9,http://tfim.example.com/TrustServerWST13/services/RequestSecurityToken
    server = 9,http://server2.jkhle.com/TrustServerWST13/services/RequestSecurityToken
  2. Once the WebSEAL configuration file has been updated with the junction configuration and the WebSEAL service has been restarted, the actual junction itself can be created. Do this using the pdadmin server task <server-name> create command. Use the -Y junction flag to indicate that the junction should be Kerberos-enabled.
    Note: Also be sure to add any other flags that are relevant for your backend application here too. Listing 6 shows the creation of a TCP-based Kerberos junction.
    Listing 6. Junction create command
    pdadmin sec_master> s t default-webseald-server2.jkhle.com create -t tcp \
      -h server1.jkhle.com -Y /iis
    Created junction at /iis
    
    pdadmin sec_master> server task default-webseald-server2.jkhle.com show /iis
        Junction point: /iis
        Type: TCP
        Junction hard limit: 0 - using global value
        Junction soft limit: 0 - using global value
        Active worker threads: 0
        Basic authentication mode: filter
        Forms based SSO: disabled
        TFIM junction SSO: yes
        Authentication HTTP header: do not insert
        Remote Address HTTP header: do not insert
        Stateful junction: no
        Boolean Rule Header: no
        Scripting support: no
        Preserve cookie names: no
        Cookie names include path: no
        Transparent Path junction: no
        Delegation support: no
        Mutually authenticated: no
        Insert WebSphere LTPA cookies: no
        Insert WebSEAL session cookies: no
        Request Encoding: UTF-8, URI Encoded
        Server 1:
            ID: 98fa4d16-3e73-11dd-b339-000c2944bd3b
            Server State: running
            Operational State: Online
            Hostname: server1.jkhle.com
            Port: 80
            Virtual hostname: server1.jkhle.com
            Server DN:
            local IP address:
            Query_contents URL: /cgi-bin/query_contents
            Query-contents: unknown
            Case insensitive URLs: no
            Allow Windows-style URLs: yes
            Current requests : 0
            Total requests : 25
  3. Finally the new Kerberos junction can be tested. For the testing of the environment documented within this article the following changes were made to the IIS configuration:
    • Windows integrated authentication was enabled using the IIS management console.
    • The IIS site was modified such that identity impersonation is enabled.
    • A simple whoami.aspx script was written which included the identity in the response. This script obtained the identity using "<% Response.Write(System.Security.Principal.WindowsIdentity.GetCurrent().Name) %>".
    A client can be used to request the new whoami.aspx script on the junctioned Web server. Authentication should be required to WebSEAL, but should not be required to the junctioned Web server. Listing 7 shows the result of a request which used curl as the client. For additional verification the IIS request logs can also be examined to ensure that the identity information is correct.
    Listing 7. Junction verification
    >curl -v -u testuser:passw0rd http://server2.jkhle.com/iis/whoami.aspx
    * About to connect() to server2.jkhle.com port 80 (#0)
    *   Trying 10.251.140.101... connected
    * Connected to server2.jkhle.com (10.251.140.101) port 80 (#0)
    * Server auth using Basic with user 'testuser'
    > GET /iis/whoami.aspx HTTP/1.1
    > Authorization: Basic dGVzdHVzZXI6bWVyY3VyeTE=
    > User-Agent: curl/7.18.0 (i486-pc-linux-gnu) libcurl/7.18.0 OpenSSL/0.9.8g
    > Host: server2.jkhle.com
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < content-type: text/html; charset=utf-8
    < date: Fri, 20 Jun 2008 04:16:32 GMT
    < p3p: CP="NON CUR OTPi OUR NOR UNI"
    < server: Microsoft-IIS/6.0
    < x-old-content-length: 43
    < transfer-encoding: chunked
    < x-powered-by: ASP.NET
    < x-aspnet-version: 1.1.4322
    < cache-control: private
    < Set-Cookie: PD-H-SESSION-ID=4_dpeEwDcJaQak23zeDAwtB...; Path=/
    <
    
    
    <h1>I am: JKHLE\testuser</h1>
    
    
    
    * Connection #0 to host server2.jkhle.com left intact
    * Closing connection #0

    The Kerberos delegation can also be seen in the Windows Event Viewer, under Windows Logs -> Security. See Figure 38, the important fields are the Logon fields where the username is shown and the delegation through TFIM is shown as the transited service.
    Figure 38. Windows Event Viewer
    Windows Event Viewer

Troubleshooting

The environment configuration for Kerberos junctions, as demonstrated by this article, is complex. If all of the steps contained within this article are followed there should be no real difficulties in configuring the environment correctly. However, if problems do occur the following tips might prove helpful in resolving issues:

  1. Kerberos tokens make use of time stamps to ensure that authentication does not take place using old tokens. If WebSEAL tries to access a resource on a Kerberos junction and returns an error page stating that no tokens were available, check the time stamps on all machines to ensure that they all fall within a reasonable limit. Ideally a time synchronization server should be used in the environment.
  2. After restarting the WAS - TFIM instance, it can take a few minutes for the server to be ready to generate tokens, even after the Windows Service states the service has started.
  3. Examine the log files for the various servers within your environment. Particular attention should be paid to the WebSphere Application Server SystemOut.log file and the WebSEAL log file.
  4. TFIM tracing for the Kerberos STS Module can be enabled to provide more information on the generation of the Kerberos token. This tracing is managed through the standard WebSphere logging mechanism (controlled through the WAS console). The component name of importance is com.tivoli.am.fim.sts.module.KerberosDelegationSTSModule. See Figure 39.
    Figure 39. Troubleshooting TFIM Kerberos Delegation
    Troubleshooting TFIM Kerberos Delegation - Log Level
  5. WebSEAL tracing for the TFIM client can be enabled to provide more information on attempts by WebSEAL to retrieve a Kerberos token from TFIM. This tracing is managed through the Tivoli Access Manager tracing mechanism (controlled by the 'pdadmin server task <server-name> trace' commands). The trace component of importance is pdweb.sso.tfim.
  6. Ensure that the service you have listed in the webseald-default.conf corresponds with that listed by the command shown in Listing 8, and that you have correctly configured the TFIM user with the correct delegation rights.
Listing 8. setspn -L
C:\Users\Administrator>setspn -L <IIS USERNAME>

Result:
Registered ServicePrincipalNames for CN=<IIS USERNAME>,CN=Users,DC=jkhle,DC=com:
        HTTP/server1.jkhle.com

Downloads

DescriptionNameSize
Sample RST requestrst.xml3KB
Sample whoami.aspx scriptwhoami.aspx1KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Security on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security, Tivoli (service management), Tivoli
ArticleID=322552
ArticleTitle=IBM Tivoli Access Manager: WebSEAL Kerberos Junctions
publish-date=12182008