Implementing SPNEGO TAI single sign-on for WebSphere applications with z/OS and Windows Kerberos trusted realms

The use of the SPNEGO protocol has been used to implement single sign-on solutions in many organizations where the primary Key Distribution Center (KDC) resides on a Microsoft® Active Directory® domain controller server. This article shows an alternative solution in which authentication happens at the Microsoft domain controller and z/OS® identities are managed through RACF®; a cross realm trust is configured to enable users authenticating to the domain controller access to services on z/OS using native z/OS identities. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Ben Rogers (bcrogers@us.ibm.com), Staff Software Engineer , IBM

Ben Rogers is a Staff Software Engineer for the IBM zSeries and System z9 Client Technology Center (CTC), where he specializes in enterprise security with a focus on RACF, LDAP, and WebSphere security. Before joining the CTC, Ben spent three years in the z/OS System Test organization architecting, implementing, and testing a security environment that exploited LDAP, RACF, PKI, EIM, SSL, Kerberos, and ICSF. He spent the three years prior to joining the security team testing Java on z/OS and Linux for zSeries, with a focus on Java security and test tool development. Ben holds a Bachelor's degree in Computational Mathematics from Michigan State University.



Ut Le (utle@us.ibm.com), Advisory Software Engineer , IBM

Ut V. Le is an Advisory Software Engineer for the IBM Software Group. He has worked for IBM for the past 18 years, focusing on security technology including DCE, IBM Network Authentication Services (IBM Kerberos) and SPNEGO TAI. He is currently developing WebSphere Kerberos authentication mechanism. Ut holds a Bachelor of Science degree in Computer Science from the Marist College.



18 July 2007

Also available in Chinese

Introduction

The issue of user ID and password proliferation, coupled with the ever increasing number of applications with which end users must interact, has become a critical issue for many IT shops. To this end, many organizations have turned to Kerberos technology; the underlying philosophy of Kerberos is that machines trust other machines through a third party Kerberos Key Distribution Center (KDC). For example, if a user authenticates to the KDC, that identity and authentication status is then used to request services that are in that trusted realm. In this type of scenario, users authenticate once to the KDC, and then their authentications are valid for a predetermined time period. Users can then access services on other machines that participate in this trusted network without again being prompted for a user ID and password. Another benefit is that a user’s clear text password will never flow over the network. Since fewer sign-ons are required, Kerberos authentication is viewed as one way to reduce some of the "complexity" that is seen by end users.

The SPNEGO protocol (Simple and Protected Negotiation mechanism) enables an HTTP-based Kerberos authentication solution within IBM® WebSphere® Application Server. This means that instead of requiring a WebSphere application to be Kerberos-aware, the SPNEGO Trust Association Interceptor (TAI) can be used instead to authenticate users.

Many midmarket and enterprise companies already utilize Microsoft domain controllers to provide an authentication mechanism for their distributed environments. Yet, many business critical WebSphere applications are hosted on System z™ environments with authentication and authorization provided by RACF®. This article describes how to utilize the SPNEGO TAI and establish a cross realm trust between a z/OS KDC and a Microsoft domain controller to enable users to access to WebSphere applications on z/OS with their domain identities. The solution presented here describes how to implement this technology using a mix of Microsoft Windows® 2003 Server, Microsoft Active Directory, z/OS, WebSphere Application Server V6.1 for z/OS, and the z/OS KDC running with a store and forward (SAF) back end. The clients used will be Firefox and Internet Explorer.


Solution overview

The SPNEGO protocol enables for an HTTP-based Kerberos authentication solution within WebSphere Application Server. This means that instead of requiring an application running in WebSphere Application Server to know about Kerberos, the SPNEGO TAI can be configured to authenticate users coming into WebSphere Application Server that present a SPNEGO token. In this solution, users must log into Microsoft Active Directory (AD) and then request a WebSphere application running on z/OS that has been configured to use the SPNEGO TAI for authentication. To do this, a Kerberos cross realm trust must be established between the Windows system and the z/OS system.

In this article, the Kerberos principal short name is the same as the RACF ID. This means that you are able to set trimUserName to True when you configure the SPNEGO properties and do not have to map the Kerberos principal name to a RACF ID. If your Kerberos principal names and RACF user ID registries identify users differently, you must write a custom JAAS LoginModule to map Kerberos principal names from Active Directory to RACF IDs, and possibly from RACF IDs to Kerberos principal names. See the WebSphere Application Server Information Center for information on how to write a custom JAAS LoginModule.

Figure 1. Solution overview
Figure 1. Solution overview

Preparation

This solution requires these prerequisites:

  • Windows domain controller

    • Windows Service Pack 1 or higher
    • Windows Server 2003 Resource Kit Tools (see Resources):
      • Kerbtray.exe
      • Klist.exe
    • Windows Server 2003 Service Pack 1 32-bit Support Tools (see Resources):
      • Ksetup.exe

    Before beginning, map out the names of the systems that will be involved in this solution. To help with your mapping, Table 1 shows system elements referred to in this article that you will need to substitute with your own actual values.

    Table 1
    ItemValue in this articleNotes
    Windows Host Nameaxel.austin.ibm.com
    Windows IP address9.2.2.3
    Windows domain/Realm name WSSEC.AUSTIN.IBM.COMThe Kerberos realm name is the Microsoft domain name in UPPERCASE.
  • Window 2003 Client

    This software that is required on the Windows client is the same as the software listed above for the domain controller. Before beginning, map out the names of the systems that will be involved in this solution. As before, use Table 2 as a guide.

    Table 2
    ItemValue in this articleNotes
    Windows Host Namew2003secdev.austin.ibm.com
    Windows IP address9.3.97.87
    Windows domain/Realm name WSSEC.AUSTIN.IBM.COMThe Kerberos realm name is the Microsoft domain name in UPPERCASE.
  • System z

    On your System z server, the following minimum software (and respective fix levels) is required:

    • WebSphere Application Server V6.1 for z/OS
    • z/OS V1.6

    Before beginning, map out the names of the systems that will be involved in this solution, again using Table 3 as a guide.

    Table 3
    ItemValue in this articleNotes
    z/OS Host Namep27.pok.ibm.com
    z/OS IP address9.57.30.27
    z/OS Realm name LSREALM.POK.IBM.COMThe naming convention for realm names is that they all be in UPPERCASE.
  • Additional prerequisites

    It is a good idea to determine values for a variety of other pieces of this solution ahead of time. Here is the beginning of such a table to help you start outlining these values:

    Table 4
    ItemValue in this articleNotes
    Cross realm trust secretKERB1SECThis value is case sensitive. Be sure to enter it in UPPERCASE on the Windows platform.

Configuring the Windows domain controller

For this solution, the Windows server you use must:

  • have the Windows Kerberos utilities installed.
  • be a DNS server.
  • be a domain controller.

Software version note
During the course of the original project on which this article based, a Windows defect was raised and a fix was produced. Be sure your environment has the minimum required Windows software.

The major steps to complete this task are:

  1. Install Windows Server 2003 Resource Kit Tools
  2. Install Microsoft Windows Server 2003 Support Tools
  3. Set up Windows domain controller and domain name server
  4. Configure the KDC and kpasswd servers
  5. Configure the cross realm trust
  6. Configure forward and reverse lookup zones
  7. Test networking settings

Each of these steps is described below in detail.

  1. Install Windows Server 2003 Resource Kit Tools

    Download and install the Windows Server Resource Kit Tools (see Resources). These tools relevant to this solution are:

    • Klist.exe

      Kerberos List is a command-line tool that is used to view and delete Kerberos tickets granted to the current logon session. To use Kerberos List to view tickets, you must run the tool on a computer that is a member of a Microsoft domain. When Kerberos List is run from a client, it shows the:

      • Ticket-granting ticket (TGT) to a Kerberos Key Distribution Center (KDC) in Windows
      • Ticket-granting ticket (TGT) to Ksserver on UNIX.
    • Kerbtray.exe

      Kerberos Tray is a graphical user interface tool that displays ticket information for a computer running Microsoft's implementation of the Kerberos V5 authentication protocol. You can view and purge the ticket cache by using the Kerberos Tray tool icon located in the notification area of the desktop. By positioning the cursor over the icon, you can view the time left until the initial ticket-granting ticket (TGT) expires. The icon also changes in the hour before the Local Security Authority (LSA) renews the ticket.

  2. Install Microsoft Windows Server 2003 Support Tools

    Download and install the Microsoft Windows Server 2003 Support Tools (see Resources). The tool relevant to this solution is:

    • Ksetup.exe

      Kerberos Setup is a command-line tool you can use to configure Windows for Kerberos V5 interoperability. Use this utility to setup a realm entry for a Kerberos V5 realm by defining a list of KDC servers and "kpasswd" server for the realm. You can also set up local account to Kerberos V5 account mappings, which is necessary to inform the operating system how to authorize a specific security principal. This links authorization data to an identity. Windows domains do not need this data because they get it through other means.

      1. Set the computer's password in the Kerberos realm. A Kerberos realm (and Windows domain) tracks computers joined to them using a shared secret in the form of the computer's password. When joining a Kerberos realm, a host principal must be created. The password used by the realm to create the host key must be entered using this command so that Windows can decode host tickets presented to it.
      2. Set up a list of KDCs for that realm.
      3. Set up a kpasswd server for that realm.
      4. Change a user's password in a Kerberos V5 realm.
  3. Set up Windows domain controller and domain name server

    It is assumed that Active Directory has already been set up. If AD and the domain name server (DNS) are not already set up, you can use the Window dcpromo.exe command to install and configure AD and DNS. Since Active Directory and KDC are part of the same server and both provide the essential authentication service for the Windows environment, they also share the same storage for authentication data.

  4. Configure the KDC and kpasswd servers

    You need to let Windows know where to find the z/OS KDC and password server. The ksetup /AddKdc command is used to define a KDC entry for the given realm. If you omit KdcName, then the DNS can be used to locate KDCs. This is an important point regarding how the server locates KDCs. See the examples below.

    ksetup /AddKdc <RealmName> [KdcName]
    ksetup /AddKdc LSREALM.POK.IBM.COM p27.pok.ibm.com
    ksetup /AddKpasswd <Realmname> <KpasswdName>
    ksetup /AddKpasswd LSREALM.POK.IBM.COM p27.pok.ibm.com
  5. Configure the cross realm trust

    To configure a cross realm trust between z/OS and Windows:

    1. Open the Active Directory Domains and Trusts utility from the z/OS Administrative Tools menu.
    2. Next, Right click on the Windows domain with which you wish to associate a trust with the z/OS system, and select Properties.
      Figure 2. Associate Windows domain with z/OS system
      Figure 2. Associate Windows domain with z/OS system
    3. Select the New Trust... button to open the New Trust wizard.
      Figure 3. New Trust Wizard
      Figure 3. New Trust Wizard
    4. Click Next to start the wizard.
    5. Enter the name of the z/OS realm that you wish to have this Windows system trust. In this example, the realm name here is LSREALM.POK.IBM.COM. Be sure to enter the realm name in UPPERCASE.
      Figure 4. Enter trust name
      Figure 4. Enter trust name
    6. For Trust Type, select Realm trust.
      Figure 5. Enter trust type
      Figure 5. Enter trust type
    7. For Transitivity of Trust, select Nontransitive.
      Figure 6. Select transitivity of trust
      Figure 6. Select transitivity of trust
    8. For Direction of Trust, select Two-way.
      Figure 7. Select direction of trust
      Figure 7. Select direction of trust
    9. Enter the password. Be sure to enter the password in UPPERCASE. The reason this is necessary is due to the manner in which the RACF RDEFINE command converts all characters to UPPERCASE before submitting to RACF. If the password case is not matched, the trust will not be valid.
    10. Click Next after verifying all the information you have entered is correct.
    11. Select Finish.
    12. You will now see two entries indicating that a two way trust has been configured (Figure 8).
      Figure 8. Two way trust has been configured
      Figure 8. Two way trust has been configured
    13. The system must be rebooted for these changes to take effect, so reboot the system now.
  6. Configure forward and reverse lookup zones

    For this solution to work, the Windows system must be able to correctly resolve the hostname of the z/OS REALM. To enable this, you must configure both a forward lookup zone and a reverse lookup zone in the Windows DNS.

    1. Create a forward lookup zone

      1. Bring up the DNS administration tool in Windows by selecting Start => Administrative Tools => DNS.
      2. Right-click on Forward Lookup Zone and selecting New Zone... (Figure 9).
        Figure 9. Create new forward lookup zone
        Figure 9. Create new forward lookup zone
      3. Select Next to start the wizard.
      4. Select Primary Zone. Leave Store the zone in Active Directory checked, and select Next.
      5. Select To All domain controllers...
      6. Enter the Zone name (also known as the domain) of the System z server. Typically, a fully qualified hostname will look something like <hostname>.some.domain.name.com. For the purpose of this article, the fully qualified hostname of the System z server is p27.pok.ibm.com so the zone is pok.ibm.com. After entering the zone name, click Next.
        Figure 10. Enter Zone name
        Figure 10. Enter Zone name
      7. Select Do not allow dynamic updates and click Next.
      8. Validate the information you have entered is correct and select Finish.
        Figure 11. Verify new zone information
        Figure 11. Verify new zone information
      9. You will now see a folder under Forward Lookup Zone that corresponds to the zone (domain) of the System z server (Figure 12).
        Figure 12. New forward lookup zone folder
        Figure 12. New forward lookup zone folder
      10. Next, you need to create a new host entry in this zone. You will create an entry for the System z server, which is p27.pok.ibm.com. Right-click on the zone just created and select New Host (A)...
        Figure 13. Create new host entry
        Figure 13. Create new host entry
      11. Enter the host name and the IP address of the host. You should see a fully qualified domain name (FQDN) that matches the real FQDN of the System z host. Select Add Host.
        Figure 14. Enter host address information
        Figure 14. Enter host address information
      12. You now need to create a text entry that defines the z/OS realm and the system which is part of that realm. To start, Right click on the zone you just created and select Other new records...
        Figure 15. Create a text entry
        Figure 15. Create a text entry
      13. Select Text (TXT) as the resource record type.
        Figure 16. Select resource record type
        Figure 16. Select resource record type
      14. This record name is _kerberos and the Text of this record must be the full System z realm name. In this example, the realm is LSREALM.POK.IBM.COM. The FQDN will end up being: _kerberos.your.fully.qualified.domain.com. After entering these values, click OK.
        Figure 17. Enter text values
        Figure 17. Enter text values
      15. You next need to create four service location records. You will create a _kerberos and _kpasswd service for both TCP and UDP, which will result in four unique entries. To do this, right-click again on the zone you created above and select Other new records...
        Figure 18. Create service location records
        Figure 18. Create service location records
      16. Select Service Location (SRV) as the resource record type.
        Figure 19. Select resource record type
        Figure 19. Select resource record type
      17. You will first create the _kerberos TCP service. From the pull down menus, select _kerberos for Service and _tcp for Protocol. Be sure the Port number matches the port defined on the z/OS system for the KDC service. Enter the fully qualified host name of the z/OS system. In this example, the name is p27.pok.ibm.com.
        Figure 20. Enter values for the TCP service location record
        Figure 20. Enter values for the TCP service location record
      18. Next, you will create the _kerberos UDP service. Select _kerberos and _udp from the pull down menus. Again, be sure the Port number matches the port defined on the z/OS system for the KDC service. Enter the fully qualified host name of the z/OS system. As before, the name is p27.pok.ibm.com.
        Figure 21. Enter values for the UDP service location record
        Figure 21. Enter values for the UDP service location record
      19. Create the _kpasswd TCP service by selecting _kpasswd for Service and _tcp for Protocol. Change the port to 464 (or whatever port matches your z/OS password server port). Again, enter the fully qualified host name of the z/OS server offering this service.
        Figure 22. Enter values for the TCP service location record
        Figure 22. Enter values for the TCP service location record
      20. Finally, create the _kpasswd UDP service by selecting _kpasswd for Service and _udp for Protocol. Change the port to 464 (or whatever port matches your z/OS password server port), and then enter the fully qualified host name of the z/OS server offering this service.
        Figure 23. Enter values for the UDP service location record
        Figure 23. Enter values for the UDP service location record
      21. Now, all services have been defined to the Windows DNS. Make sure there is a _kerberos Text entry that lists the System z server's realm name, and a host entry that lists the System z server's host name and IP address.
        Figure 24. Check text entries
        Figure 24. Check text entries
      22. Next, check the TCP service records and make sure both a _kerberos and _kpasswd service location record exist for this entry, and that they point to the System z server hosting this service. Ensure the port, as noted in the third set of [brackets], is correct for each service.
        Figure 25. Check TCP service location records
        Figure 25. Check TCP service location records
      23. Next, check the UDP service records and make sure both a _kerberos and _kpasswd service location record exist for this entry, and that they point to the System z server hosting this service. Again, ensure the port is correct for each service.
        Figure 26. Check UDP service location records
        Figure 26. Check UDP service location records
    2. Create a reverse lookup zone

      To create a reverse lookup zone for the System z server:

      1. In the DNS Administration window, right-click on the Reverse Lookup Zone folder and select New Zone...
        Figure 27. Create reverse lookup zone
        Figure 27. Create reverse lookup zone
      2. Select Next to begin the wizard.
      3. Select Primary Zone, then Next.
      4. Select To all domain controllers, then Next.
      5. Select Network ID and enter the first three octets of the System z server's IP address. In this example, if the full IP address of p27.pok.ibm.com is 9.57.30.27, then the first three octets are 9.57.30. Click Next.
        Figure 28. Specify network ID values
        Figure 28. Specify network ID values
      6. Select Do not allow dynamic updates, then Next.
      7. Verify the information, then click Finish.
        Figure 29. Verify new zone information
        Figure 29. Verify new zone information
      8. Next, create a new pointer record for the reverse lookup zone you just created. To do this, right-click on the new zone and select New Pointer (PTR)...
        Figure 30. Create new pointer record
        Figure 30. Create new pointer record
      9. Associate the system p27.pok.ibm.com with the IP address 9.57.30.27 by entering the fully qualified host name into the Host name field, and the last octet into the Host IP number (Figure 31). Alternatively, if the forward zone has already been defined for this System z server, you can use the Browse button to search for the host p27.pok.ibm.com Click OK when finished.
        Figure 31. Enter pointer record data
        Figure 31. Enter pointer record data
      10. Confirm that there is a pointer from 9.57.30.27 to p27.pok.ibm.com in the reverse lookup zone 9.57.30.x.
        Figure 32. Confirm reverse lookup zone data
        Figure 32. Confirm reverse lookup zone data

    Reboot the system after the forward and reverse lookup zones have been created.

  7. Test networking settings

    You must ensure the both forward and reverse lookups between the z/OS system and the Windows system are possible. To do this, perform a ping by host name (Figure 33) and IP address (Figure 34), plus an nslookup of the z/OS host name (Figure 35).

    Figure 33. Ping with host name
    Figure 33. Ping with host name
    Figure 34. Ping with IP address
    Figure 34. Ping with IP address
    Figure 35. nslookup with z/OS host name
    Figure 35. nslookup with z/OS host name

Windows 2003 client configuration

Install the Windows Server 2003 Resource Kit Tools and the Windows Server 2003 Service Pack 1 Support Tools (see Resources), then configure these settings:

  1. Kerberos protocol registry settings

    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Domains

      The Domains subkey stores information about non-Windows Kerberos realms. Use the Kerberos Setup (ksetup.exe) tool to add the KDC host name (p27.pok.ibm.com) for your Kerberos realm (LSREALM.POK.IBM.COM):

      C:\>ksetup /AddKdc LSREALM.POK.IBM.COM p27.pok.ibm.com

      Use the ksetup.exe tool to list the Kerberos realm information:

      default realm = wssec.austin.ibm.com (NT Domain)
      LSREALM.POK.IBM.COM:
             		kdc = p27.pok.ibm.com
             		Realm Flags = 0x0 none
      	
      No user mappings defined.

      Use the regedit.exe utility to make sure the z/OS Kerberos realm LSREALM.POK.IBM.COM is present (Figure 36).

      Figure 36. Run regedit.exe
      Figure 36. Run regedit.exe
    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\HostToRealm

      This subkey stores host-to-realm mapping information. There is no tool available to create this subkey, so if this subkey is not present, you must use regedit.exe to create it manually:

      1. Create the key HostToRealm: HKLM\System\CurrentControlSet\Control\Lsa\Kerberos\HostToRealm.
      2. Add a key name: LSREAM.POK.IBM.COM.
      3. In the key name LSREALM.POK.IBM.COM, create a value: SpnMappings.
      4. Add a REG_MULTI_SZ for pok.ibm.com.
      Figure 37. Create HostToRealm key
      Figure 37. Create HostToRealm key
  2. Browser SSO configuration

    The browser client you use must be configured to use the SPNEGO protocol to negotiate authentication mechanisms. Either Microsoft Internet Explorer Version 6.0 SP1 (or higher) or Mozilla Firefox 1.5.0.7 is required. Earlier versions of Mozilla, plus other browsers that support SPNEGO, might work they have not been tested with this solution.

    • Internet Explorer

      To ensure that your browser is enabled to perform SPNEGO authentication:

      1. At the desktop, log in to the Windows AD domain.
      2. Launch Internet Explorer.
      3. In the browser window, select Tools => Internet Options => Security.
      4. Select the Local intranet icon and click Sites.
      5. In the Local intranet window, ensure that the check box to Include all local (intranet) not listed in other zones is selected, and then click Advanced.
      6. In the Local intranet window, fill in the Add this Web site to the zone field with the host name's Web address so that single sign-on (SSO) can be enabled to the list of Web sites shown in the Web sites field (Figure 38). (Your site IT staff can provide this information.) Click OK to complete this step and close the Local intranet window.
      7. On the Internet Options window, click the Advanced tab and scroll to Security settings. Ensure that the Enable Integrated Windows Authentication (requires restart) box is selected.
      8. Click OK. Restart Internet Explorer to activate this configuration.
      Figure 38. Add Web sites to the zone
      Figure 38. Add Web sites to the zone
    • Firefox

      To ensure that your browser is enabled to perform SPNEGO authentication:

      1. At the desktop, log in to the Windows AD domain.
      2. Launch Firefox.
      3. At the address field, type about:config.
      4. For Filter, type network.n.
      5. Double click on network.negotiate-auth.trusted-uris (Figure 39). This preference lists the sites that are permitted to engage in SPNEGO authentication with the browser. Enter your list of trusted domains or URLs, delimited by commas.
      6. If the deployed SPNEGO solution is using the advanced Kerberos credential delegation feature, double click on network.negotiate-auth.delegation-uris. This preference lists the sites for which the browser may delegate user authorization to the server. Enter a comma-delimited list of trusted domains or URLs.
      7. Click OK. The configuration appears as updated.
      8. Restart your Firefox browser to activate this configuration.
      Figure 39. Confirm Firefox SPNEGO authentication
      Figure 39. Confirm Firefox SPNEGO authentication

Configuring z/OS

This solution uses an SAF-based Kerberos solution, not an NDBM- (New Database Manager) based Kerberos solution. This means that not all UNIX Kerberos commands are available; for instance, the kadmin command does not function. Instead, the administrator must know how to translate these commands into RACF commands.

RACF definitions

Since this solution assumes that user IDs will be identical between Windows and RACF, you must ensure that you have similar IDs for your testing. In this example, the ID UTLE will be used to validate the setup:

  1. Basic RACF setup items

    1. Create the user that will own the Kerberos-started task:
      ADDUSER SKRBKDC DFLTGRP(SYS1) NOPASSWORD OMVS(UID(0) PROGRAM('/bin/sh') 
      HOME('/etc/skrb/home/kdc'))
    2. If not already active, activate the APPL class:
      SETROPTS CLASSACT(APPL) RACLIST(APPL)
    3. Define the SKRBKDC profile in the APPL class:
      RDEFINE APPL SKRBKDC UACC(READ)
    4. The PTKTDATA class is also required by Kerberos when using a RACF back end. If it is not yet active on your system, activate it:
      SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)
    5. Next, you need to create a key to be used to mask some values in RACF for the KDC:
      RDEFINE PTKTDATA SKRBKDC UACC(NONE) SSIGNON( KEYMASKED(3734343237343131))
    6. RACLIST the APPL and PTKTDATA classes:
      SETROPTS RACLIST(APPL PTKTDATA) REFRESH
    7. Define the IRR.RUSERMAP profile in the FACILITY class and grant it universal READ access:
      RDEFINE FACILITY IRR.RUSERMAP UACC(READ)
      SETROPTS RACLIST(FACILITY) REFRESH
    8. Define the SKRBKDC started task:
      RDEFINE STARTED SKRBKDC.** STDATA(USER(SKRBKDC))
      RDEFINE STARTED SKRBWTR.** STDATA(USER(SKRBKDC))
    9. Create the Kerberos admin ID KADMIN:
      ADDUSER KADMIN DFLTGRP(SYS1) PASSWORD(pw)
      ALTUSER KADMIN PASSWORD(kadm1sec) NOEXPIRED KERB(KERBNAME(kadmin/admin))
    10. Grant users of this service a Kerberos segment (a Kerberos ID). (Since the only common algorithm between Windows and z/OS is DES, users must be restricted from using the DESD and DES3 algorithms.)
      ALTUSER UTLE KERB(KERBNAME(UTLE) ENCRYPT(DES NODES3 NODESD)) PASSWORD(KRB1TST) NOEXPIRED
  2. Create the Kerberos service principal name for WebSphere Application Server

    1. Create a Kerberos segment (ID) for the RACF ID that owns the WebSphere Application Server control region started task. In this solution, make sure the RACF ID is ASCR1. (The Kerberos ID KERBNAME must be HTTP/<fully qualified system name>.)

      ALTUSER ASCR1 KERB(KERBNAME(HTTP/p27.pok.ibm.com))
    2. Next, generate the Kerberos key for this user. To generate this key, a password must be associated with this ID; however, this ID should not be able to log onto the system. Because of this condition, the following two commands must be run whenever a new Kerberos key is needed (the WebSphere or KDC administrator must know this password to be able to create an entry in the keytab file):

      ALTUSER ASCR1 PASSWORD(was1krb) NOEXPIRED
      ALTUSER ASCR1 NOPASSWORD
    3. Next, verify that this user has a valid Kerberos segment and a key:

      LISTUSER ASCR1 KERB NORACF
       USER=ASCR1
       KERB INFORMATION
       ----------------
       KERBNAME= HTTP/p27.pok.ibm.com
       KEY VERSION= 001
       KEY ENCRYPTION TYPE= DES NODES3 NODESD
  3. Create the realm definition

    Since the KDC is using RACF as a back end, you must create a REALM definition within RACF. This is done by creating a default realm as follows (the class is REALM and the profile is KERBDFLT; this must exist in order to have Kerberos use RACF as its backend):

    RDEFINE REALM KERBDFLT KERB(KERBNAME(LSREALM.POK.IBM.COM) PASSWORD(secret) MINTKTLFE(15) 
    DEFTKTLFE(36000) MAXTKTLFE(86400))

    If required by your installation, RACLIST the REALM class:

    SETROPTS RACLIST(REALM) REFRESH
  4. Create the cross realm trust

    Since the only algorithm common between Windows and z/OS is DES, you should prohibit the use of DESD and DES3 by z/OS. You can accomplish this when defining the cross realm trust. This is a sufficient control to prevent this behavior, but if your Kerberos environment only interacts with a Windows KDC, it might also be beneficial to prohibit this behavior when defining each user's Kerberos ID. This is shown above when modifying a user. (Be sure to enter the password in UPPERCASE on both the Windows and z/OS side.)

    RDEFINE REALM /.../WSSEC.AUSTIN.IBM.COM/KRBTGT/LSREALM.POK.IBM.COM KERB(PASSWORD(KERB1SEC)
    ENCRYPT(DES NODESD NODES3))
    
    RDEFINE REALM /.../LSREALM.POK.IBM.COM/KRBTGT/WSSEC.AUSTIN.IBM.COM KERB(PASSWORD(KERB1SEC)
    ENCRYPT(DES NODESD NODES3))
  5. Start the KDC

    You should now be able to start the KDC.

    START SKRBKDC

z/OS Kerberos configuration

These are the configuration options necessary for the KDC:

  1. Create /etc/krb5 link

    This section is included to make life easier for the various components involved. The default location of the Kerberos configuration files on z/OS is /etc/skrb. For most other platforms, it is /etc/krb5. Since the code between the z/OS SPNEGO TAI and all other platforms is common, it is best to create a symbolic link so that z/OS appears to have an /etc/krb5 directory. This can be done with the following command:

    ln -s /etc/skrb /etc/krb5
  2. Edit /etc/skrb/krb5.conf

    This file contains the REALM definition and various configuration options for the KDC:

    ;---------------------------------------------------------------------;
    ;  Kerberos configuration file for testing the SPNEGO TAI             ;
    ;                                                                     ;
    ;  File Name: /etc/krb5/krb5.conf                                     ;
    ;                                                                     ;
    ;---------------------------------------------------------------------;
    
    [libdefaults]
    
    ; The default_realm must match the realm name in RACF. See the
    ; profile KERBDFLT in the REALM class..
    default_realm = LSREALM.POK.IBM.COM
    kdc_default_options = 0x40000000
    default_keytab_name = FILE:/etc/skrb/krb5.keytab
    use_dns_lookup=0
    use_ldap_lookup=0
    
    
    ; Default encryption types if DES3 is not supported
    default_tkt_enctypes = des-cbc-md5 des-cbc-crc
    default_tgs_enctypes = des-cbc-md5 des-cbc-crc
    
    ; We must which systems are in which realm. LSREALM contains the z/OS
    ; system and WSSEC contains the Windows 2003 server.
    [realms]
    LSREALM.POK.IBM.COM = {
        kdc = p27.pok.ibm.com:88
        kpasswd_server = p27.pok.ibm.com:464
    }
    
    WSSEC.AUSTIN.IBM.COM = {
        kdc = axel.wssec.austin.ibm.com:88
        kpasswd_server = axel.wssec.austin.ibm.com:464
    }
    
    ; We explicitly define host names to realms.
    [domain_realm]
  3. Edit /etc/skrb/home/kdc/envar

    This file contains various environmental settings required by the KDC:

    #-----------------------------------------------------------------#
    #  Environment variable definitions for the Kerberos Server       #
    #-----------------------------------------------------------------#
    #
    #  General server options
    #
    SKDC_DATABASE=SAF
    SKDC_PORT=88
    SKDC_KPASSWD_PORT=464
    SKDC_KADMIN_PORT=749
    SKDC_NETWORK_THREADS=15
    SKDC_LOCAL_THREADS=15
    SKDC_LOGIN_AUDIT=FAILURE
    SKDC_TKT_ENCTYPES=des-cbc-md5,des-cbc-crc
    #
    #  System configuration options
    #
    LANG=En_US.IBM-1047
    TZ=EST5EDT
    NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/En_US.IBM-1047/%N
    #
    #  Message/debug options
    #
    _EUV_SVC_MSG_LOGGING=STDOUT_LOGGING
    _EUV_SVC_MSG_IDENTITY=SKRBKDC
    _EUV_SVC_MSG_FACILITY=AUTH
    _EUV_SVC_DBG_MSG_LOGGING=1
    _EUV_SVC_DBG=*.8
    _EUV_EXC_ABEND_DUMP=0
    _EUV_SVC_MSG_LEVEL=
    #
    #  These options are used to tell the server where it can find the
    #  configuration and keytab file if they are not in the default directory
    #
    KRB5_CONFIG=/etc/skrb/krb5.conf
    KRB5_KTNAME=/etc/skrb/krb5.keytab
  4. Create a Kerberos keytab (krb5.keytab) file

    The SPNEGO TAI currently requires the use of a keytab file for the SPN. Use the Java™ Kerberos ktab command, <$WAS_HOME>/java/bin/ktab, to create a keytab file. From a command line, use the ktab -help command to get the usage for this command. For example:

    (P27)CTC03:/PYRSA1/usr/lpp/zWebSphere/V6R1/java/J5.0/bin(189):>ktab -help
    Usage: java com.ibm.security.krb5.internal.tools.Ktab [options]
    Available options:
      -l					list the keytab name and entries
      -a <principal_name> [password] 	add an entry to the keytab
      -d <principal_name>     	delete an entry from the keytab
      -k <keytab_name>		specify keytab name and path with FILE: prefix
    1
    #

    From a command line, use the ktab command to add the SPN to a default keytab file. For example:

    (P27)CTC03:/PYRSA1/usr/lpp/zWebSphere/V6R1/java/J5.0/bin(201):>ktab -a
    HTTP/p27.pok.ibm.com@LSREALM.POK.IBM.COM ot56prod
    
    Done!
    
    Service key for principal HTTP/p27.pok.ibm.com@LSREALM.POK.IBM.COM saved

    From a command line, verify that the correct SPN is in the default keytab file. For example:

    (P27)CTC03:/PYRSA1/usr/lpp/zWebSphere/V6R1/java/J5.0/bin(202):>ktab
    1 entries in keytab, name: /etc/skrb/krb5.keytab
            KVNO    Principal
            ----    ---------
            1       HTTP/p27.pok.ibm.com@LSREALM.POK.IBM.COM

Configure WebSphere Application Server for System z for SPNEGO TAI

This section describes the WebSphere Application Server configuration changes needed for the SPNEGO TAI.

  1. Enable global and application security

    Global security and application security must be turned on with the user registry and the local operating system for WebSphere Application Server to enable this functionality. From the WebSphere Application Server admin console:

    1. Expand Security.
    2. Select Secure administration, applications, and infrastructure.
    3. Check Enable administrative security.
    4. Check Enable application security.
    5. For Available realm definitions, select Local operating system and click Set as current. See the WebSphere Application Server Information Center for information on configuring the local operation system.
    Figure 40. Enable WebSphere Application Security
    Figure 40. Enable WebSphere Application Security
  2. Enable Trust Association Interceptor (TAI)

    If TAI is not enabled, it must be turned on. From the admin console:

    1. Expand Security.
    2. Select Secure administration, applications, and infrastructure.
    3. Expand Web security.
    4. Select Trust association.
    5. Check Enable trust association.
    Figure 41. Enable trust association
    Figure 41. Enable trust association
  3. Enable SPNEGO TAI

    You must enable SPNEGO TAI for WebSphere Application Server. To enable SPNEGO TAI for the control region:

    1. From the admin console, expand Servers.
    2. Select Application servers.
    3. Select Server1.
    4. Under Java and Process Management, select Process definition.
    5. Click Control, then select Virtual Java Machine.
    6. In the Generic JVM arguments box, enter -Dcom.ibm.ws.security.spnego.isEnabled=true (Figure 42). If you want to turn on the JGSS and KRB5 traces, then enter:
      -Dcom.ibm.security.jgss.debug=all -Dcom.ibm.security.krb5.Krb5Debug=all
      Figure 42. Enable SPNEGO for WebSphere Application Server
      Figure 42. Enable SPNEGO for WebSphere Application Server control region

    To enable SPNEGO TAI for server regions:

    1. From the admin console, expand Servers.
    2. Select Application servers.
    3. Select Server1.
    4. Under Java and Process Management, select Process definition.
    5. Click Servant and select Virtual Java Machine.
    6. In Generic JVM argument box, enter -Dcom.ibm.ws.security.spnego.isEnabled=true. If you want to turn on the JGSS and KRB5 traces, enter:
      -Dcom.ibm.security.jgss.debug=all -Dcom.ibm.security.krb5.Krb5Debug=all
      Figure 43. Enable SPNEGO for WebSphere Application Server server region
      Figure 43. Enable SPNEGO for WebSphere Application Server server region
  4. Configure SPNEGO properties

    Finally, you now can add SpnegoTAIProperties for SPN1 to use the default filterClass, and to intercept *snoop* requests for the host p27.pok.ibm.com.

    Figure 44. SPNEGO properties
    Figure 44. SPNEGO properties

    Stop and restart WebSphere Application Server for the SPNEGO TAI configuration to take effect.


Testing SPNEGO TAI set up

On the Windows client machine, login to the domain controller with a domain account, open your browser client (either Internet Explorer or Firefox) and type in the URL: http://p27.pok.ibm.com:9080/snoop. If it displays the snoop content without prompting for user name and password, that means you have successfully set up the Single Sign On Using Kerberos and SPNEGO with z/OS and Microsoft Kerberos cross realms.


Debugging tips

Here are some tips for basic problem determination related to this solution.

Enable z/OS Kerberos trace

To turn debug on and off for the KDC, you must be able to modify the Kerberos started task. The general syntax of the command for this is:

F SKRBKDC,parmaters

To turn debug on, issue this command:

F SKRBKDC,DEBUG ON

To turn debug off:

F SKRBKDC,DEBUG OFF

Debug levels for the KDC can be set through environment variables or dynamically using the modify command. The syntax for setting debug levels dynamically is:

F SKRBKDC,DEBUG subcomponent.level[,subcomponent.level, ...]

Table 4 lists of all of the subcomponents that can be specified in the DEBUG modify command. Levels are numeric values 0 through 9, where 0 turns debug off for that component and 9 generates the most information, including memory dumps. The * can be used to select all subcomponents.

Table 5
Debug componentDescription
KRB_APIKerberos API entry/exit
KRB_GENERALGeneral Kerberos messages
KRB_CCACHECredentials cache messages
KRB_RCACHEReplay cache messages
KRB_CRYPTOCryptography messages
KRB_GSSAPIGSS-API messages
KRB_KEYTABKey table messages
KRB_LIBKerberos library messages
KRB_ASN1ASN.1 messages
KRB_OSOperating system interface messages
KRB_KDCKDC messages
KRB_KDBKerberos database messages
KRB_KUTKerberos utility messages
KRB_RPCRPC messages
KRB_ADMINKerberos administration messages

Here is an example of how to turn on level 9 for all subcomponents:

F SKRBKDC,DEBUG *.9

Here is an example of how to turn on level 1 for the two subcomponents KRB_KDC and KRB_KEYTAB:

F SKRBKDC,DEBUG KRB_KDC.1,KRB_KEYTAB.1

The IBM Java Generic Security Service (JGSS) and IBM SPNEGO providers use a Java virtual machine (JVM) custom property to control trace information. The SPNEGO TAI uses the JRas facility to enable an administrator to trace only specific classes. Use the following important trace specifications or JVM custom properties to debug the TAI using tracing:

Enable IBM JGSS/KRB5 and WebSphere Application Server security trace
TraceUse
com.ibm.security.jgss.debugSet this JVM custom property to all to trace through JGSS code. Messages appear in the trace.log file and in SystemOut.log.
com.ibm.security.krb5.Krb5DebugSet this JVM custom property to all to trace through the Kerberos5-specific JGSS code. Messages appear in the trace.log file, and in SystemOut.log.
com.ibm.ws.security.security.*Set this trace on using the administrative console, by selecting Troubleshooting => Logging and Tracing => server1 => Change Log Detail Levels => com.ibm.ws.security.security.*. Messages appear in the trace.log file.

Enable Windows Kerberos trace

To enable Kerberos event logging on a specific computer:

  1. Start the Registry Editor on the selected machine. (Caution: Incorrectly editing the registry might severely damage your system. Before making changes to the registry, you should back up any valued data on the computer.)
  2. Add the following registry value: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters
    • Registry Value: LogLevel
    • Value Type: REG_DWORD
    • Value Data: 0x1
  3. If the Parameters subkey does not exist, create it. (Remove this registry value when it is no longer needed so that performance is not degraded on the computer. Also, you can remove this registry value to disable Kerberos event logging on a specific computer.)
  4. Quit Registry Editor, and then restart the computer.

Conclusion

This article illustrated how to configure a z/OS RACF KDC and a Microsoft Active Directory KDC in a cross realm trust model. In this solution, users authenticate to the Microsoft domain controller, but access z/OS services on WebSphere Application Server as their RACF identity; WebSphere Application Server on z/OS can continue to leverage the strong security services offered by RACF while offering users a single sign-on experience.

An important observation of this particular solution is that the user identities between AD and RACF must be equivalent; for example, you have an ID of "ROGERS" in the Active Directory server and "ROGERS" in RACF. In reality, few organizations have an organization-wide naming convention that mandates their AD users have the same ID as their RACF users. This solution does not address the case in which user IDs are different between platforms. A sample JAAS login module that performs this type of mapping can be found in the WebSphere Application Server Information Center.

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=240797
ArticleTitle=Implementing SPNEGO TAI single sign-on for WebSphere applications with z/OS and Windows Kerberos trusted realms
publish-date=07182007