Configuring a WebSphere DataPower Kerberos-secured backend server, Part 1: Using the DataPower Web Graphical User Interface

This first in a 2-part article series de-mystifies the work required to set up a WebSphere® DataPower configuration that uses a Kerberos-secured backend server. This first article describes how to create these configurations in a static fashion using the DataPower Web Graphical User Interface. Part 2 describes how the DataPower custom stylesheet objects are used to configure a gateway to a Kerberos backend server in a more dynamic fashion.

Michael McMahon (mmcmaho@us.ibm.com), Advisory Software Engineer, IBM

Photo of Michael McMahonMichael McMahon is an Advisory Software Engineer for IBM working in Research Triangle Park, NC. He has worked on a variety of development teams and projects in the past and currently works in the IBM DataPower and IBM PureApplication System support organization.



Bill Barrus (bbarrus@us.ibm.com), Senior Software Engineer, Certified IT Specialist, IBM

Photo of Bill BarrusBill Barrus is a Senior Software Engineer in IBM Software Group. He began his IBM career performing mechanical design trade-off studies for the U.S. Navy F-14 avionics upgrade program. He contributed to emerging business opportunity challenges in support of CATIA Engineering Analysis, Lotus Workplace Client Technology, and WebSphere Voice Server. He was the World Wide team lead of WebSphere DataPower support to IBM Business Partners and moved to lead IBM SWG L2 support's DataPower Security team, and is now technical support team lead for the innovative, new cloud computing offering - IBM PureApplication System.



Lisa Rich (lisarich@us.ibm.com), Advisory Software Engineer, IBM

Photo of Lisa RichLisa Rich is an Advisory Software Engineer in IBM Software Group. She serves as a technical support lead for WebSphere DataPower SOA Appliances, specializing in DataPower Security. Prior to working with DataPower, she has served as an IBM SWG L2 and L3 support specialist for WebSphere Application Server, WebSphere Studio Enterprise Developer and EGL, and CICSPlex System Manager. Lisa is also a member of the technical support team for IBM PureApplication System and IBM Workload Deployer.



October 2013 (First published 18 July 2012)

Also available in Chinese Portuguese

Introduction

As members of the DataPower support group, we frequently work with customers who have a need to connect their client applications to backend servers that are secured with Kerberos authentication. Inevitably, a large number of these customers have questions regarding how to configure a gateway or proxy to support this type of client and server solution. Kerberos can be a confusing and complicated technology to set up for the first time, which probably explains the frequency of questions related to this topic.


Kerberos solution

There are many articles that provide excellent overviews on Kerberos and describe the various components and interactions that take place as part of the Kerberos security model (see the Resources section of this article). We assume that the reader already has a basic level of knowledge of Kerberos security. We will focus on Kerberos-related activities that are directly required for DataPower configuration. In making these articles available, we hope to help avoid delays and confusion when trying to determine how to design and implement Kerberos-related solutions in DataPower.

Solution scenario

The scenario that we will be working with in this first article involves a customer that has a set of clients that need to connect to a web application on the customer's backend server. This web application is secured via Kerberos authentication. The incoming clients, however, are not secured or authenticated via Kerberos. In our example, we will assume the clients are authenticated via basic authentication and a Lightweight Directory Access Protocol (LDAP) server, but it may be one of several other forms of authentication (Note: Some exposure to LDAP is relevant as LDAP is typically used in conjunction with Kerberos). Although we typically use SSL when using basic authentication, we will not set this up in our example to keep things simple.

In order to allow these non-Kerberos clients to communicate and access our Kerberos-secured web application, you will be setting up a Multi-Protocol Gateway in DataPower. This gateway is defined to accept incoming client requests as HTTP GET requests, authenticate, and authorize the clients based on their incoming credentials, and then submit the client's request to the backend server by using a Kerberos token to authenticate with the backend server. The response returned from the backend server will then be passed back from DataPower to the requesting client. See Figure 1.

Figure 1. Overview diagram of solution scenario
Overview diagram of solution scenario

Kerberos interaction

In this example scenario, we are using WebSphere Application Server (hereafter called Application Server) as our backend server to host our web application. The web application will be the sample "snoop" application that ships with Application Server. This Application Server is configured to support Kerberos authentication so that the web application cannot be accessed without a proper Kerberos service ticket. As part of the Kerberos authentication, Application Server has access to a Kerberos keytab file that contains a Service Principal Name (SPN) and a corresponding private key. Access to this keytab file allows the Application Server to process incoming client requests that have been authenticated by the Key Distribution Center (KDC) and have received a Kerberos service ticket to allow them to talk with the web application.

In order to clear up any confusion, one important aspect of this interaction between DataPower and the backend server is that all client requests to Application Server will be sent by DataPower under a single authenticated Kerberos user ID. All incoming requests to DataPower are first authenticated and authorized by their LDAP credentials. If a user passes this authentication or authorization stage, they are considered legitimate users for accessing the web application. At this stage if there is a need, certain users can be filtered out from access to the web application. Otherwise, it is perfectly fine to send all requests to the web application under a single Kerberos user ID.

If our web application was more sophisticated and did need the actual client user ID, then one option is to pass that user ID to the web application as part of a SOAP message. Another option is discussed in the next article that is part of this series. But for now, in this article, all client requests are sent to the Kerberos-secured web application using a single mapped Kerberos user ID.


Implementing the solution in DataPower

This section illustrates what Kerberos artifacts are needed to set up the desired configuration and what commands are necessary to generate these artifacts. We will not go into detail on the Kerberos-related configuration that is required on Application Server to secure the web application, other than to briefly mention some general configuration steps and artifacts. For more information, refer to IBM Redbook: Implementing Kerberos in a WebSphere Application Server environment.

Create a Kerberos user account

In order to create a SPN to serve as your DataPower Kerberos client user ID, create a user ID in the Active Directory (AD). You will use the Active Directory Users and Computers console, running on the Domain Controller machine, and create the following user ID: dpkerbclient.

  1. To set up this user ID in the AD Users console, right-click the Users folder and choose New > User. Enter dpkerbclient in the "Full name" field and in the "User logon name" field. Click the Next button, as shown in Figure 2.
    Figure 2. New AD user
    New AD user
  2. Enter a password for this account and uncheck the "User must change password at next logon" checkbox and check the "User cannot change password" and "Password never expires" checkboxes, as shown in Figure 3. Click the Next button.
    Figure 3. New AD User options
    New AD User options
  3. Click the Finish button to complete the creation of this new user account.

Create a client SPN

You will next use the "setspn.exe" utility to create an SPN to associate with this new client account.

  1. Open a DOS command window on the Domain Controller machine and issue the following command:
    setspn -a HTTP/dpkerbclient.csupport.com dpkerbclient

    Note: "CSUPPORT.COM" is the AD realm for our AD domain. Substitute it with your appropriate realm value.

    This creates a SPN called "HTTP/dpkerbclient.csupport.com" and associates this SPN with the "dpkerbclient" user ID. The "HTTP" part of this SPN is an arbitrary, but it is a commonly used prefix. Note that the SPN is used by DataPower to identify how to find a key from a special keytab file (the keytab file is explained immediately below). It is also important to realize that this SPN is case sensitive when used by DataPower, so you must be consistent with case context when you reference this SPN. See Figure 4.

    Figure 4. Setspn command and output
    Setspn command and output

Create the client keytab file

Now that you have a user ID and SPN for accessing the web application, you will set up a Kerberos keytab file for the DataPower Kerberos configuration. As the name suggests, the keytab file contains a table of keys. Each key entry has a private key and a Service Principal Name (SPN) associated with that private key. Of course, there is other information in the keytab file, but these two items are the primary attributes that we are interested in. The keytab file contains only one key entry. This is the key and SPN for the user ID that all of the client requests will be mapped to by DataPower when invoking the web application.

While still on the Domain Controller, you will use a Windows® OS based utility, "ktpass.exe", to create our keytab file. The keytab file is later uploaded into DataPower when you configure the post processing security object.

  1. Issue the following command to generate the keytab file:
    ktpass -out c:\temp\dpkerbclient.keytab -princ
    HTTP/dpkerbclient.csupport.com@CSUPPORT.COM -mapUser dpkerbclient
    -mapOp set -pass * -crypto RC4-HMAC-NT
  2. You are prompted to enter the password for this user ID after hitting the Enter key. There may also be a Warning message indicating that the pType and the account type do not match. You can ignore this message. See Figure 5.
    Figure 5. KTPASS command and output
    KTPASS command and output

Note: "CSUPPORT.COM" is the AD realm for our AD domain. Substitute it with your appropriate realm value.

Kerberos keytab file – server application

On WebSphere Application Server, where the snoop application will be hosted, the administrator has already setup a user ID and a SPN to be used as the Server SPN. The administrator also created a keytab file for that server SPN account. This keytab file has been uploaded to Application Server to decrypt any service tickets that are sent to it.

Note: Clients send a service ticket to that Application Server. That service ticket has information encrypted in it that only the server associated with that SPN can decrypt and read (this is why Application Server needs access to the keytab file for the server SPN). This ensures that client requests are consumed by the correct destination.

Although we assume this work has already been completed by an administrator, it is important that you know what this server SPN is, in case you are called upon to assist the Application Server administrator in verifying that the Kerberos setup is correct when DataPower communicates with the backend server.

Since you are still working in the Domain Controller machine, you will also issue a setspn command to list and verify the server SPN associated with the web application server.

We assume this SPN (HTTP/oc4102831681.csupport.com in our example) was set up earlier by the WebSphere Application Server administrator and the KDC administrator. You need to find out what user ID account name is associated with the server SPN. The KDC administrator can provide that information. Once you have that information, issue a command to verify the server SPN as follows:

setspn -l <userid associated with the server application SPN>

You see the following output from this command. In our example, the account name for the server SPN, HTTP/oc4102831681.csupport.com, is "waskerb".

Registered ServicePrincipalNames for CN=waskerb,CN=Users,DC=csupport,DC=com:
  HTTP/oc4102831681.csupport.com

This verification of the server SPN eliminates the need to check this later if problems are encountered.


DataPower-related activities

Now that you have created the peripheral Kerberos artifacts, you can start working with DataPower to create a Multi-Protocol Gateway (MPG) configuration that allows your clients to make requests to the Kerberos-secured backend web application (the snoop application, in this case). As mentioned in the beginning of this article, these clients are coming into DataPower as HTTP GET requests, secured through basic authentication. DataPower accepts these requests, authenticates the user in LDAP, and then calls the backend snoop application using a Kerberos service ticket to authenticate with the backend server. The response from the snoop application is passed back to the client.

Create the Multi-Protocol Gateway

  1. Log into the DataPower console, in the "default" domain, and create a new user domain called kerbDemo.
  2. Switch to this new kerbDemo domain and click on the Multi-Protocol Gateway (MPG) icon.
  3. In the MPG panel, click the Add button and create a new MPG configuration called "kerbDemoMPG" by typing this into the "Multi-Protocol Gateway Name" field. Leave the "Type" field set to static-backend.

Define the front side settings

Define a Front Side Handler to accept a HTTP GET requests on port "50000" (this is an arbitrary port we have selected for incoming requests), and ignore all requests except those targeted for the "snoop" application.

  1. Click the "+" button and then select HTTP Front Side Handler in the combo list in the "Front Side Protocol" section on the lower right side of the MPG panel, as shown in Figure 6.
    Figure 6. Selecting Front Side Protocol Handler type
    Selecting Front Side Protocol Handler type
  2. In the resulting "Configure HTTP Front Side Handler" panel, type in kerbDemoFSH in the "Name" field, type 50000 for the "Port Number" field, and check the "GET method" checkbox below, as shown in Figure 7. Leave all other fields alone and click the Apply button.
    Figure 7. Front Side Handler settings
    Front Side Handler settings
  3. Finally, under the "Request Type" sub-section of the "Front side settings" section, click the Non-XML radio button as your clients will not be sending SOAP or XML to DataPower. Leave all other fields or attributes set to their defaults.

Define the back side settings

  1. For the back side settings, enter the URL required to access the WebSphere Application Server snoop application. In our case, it was http://9.42.90.238:11000/snoop.
  2. Under the "Response Type" sub-section of the "Back side settings" section, click the Non-XML radio button as the snoop application simply sends back a response in HTML format. Leave all other fields or attributes set to their defaults.

    See Figure 8 for the final Back side and Front side settings.

    Figure 8. Back side and Front side settings
    Back side and Front side settings

Define the Multi-Protocol Gateway policy

In this next section, you will define the MPG Policy to authenticate your incoming client and add a Kerberos token for authenticating to the backend server.

  1. Click the "+" sign under the "Multi-Protocol Gateway Policy" section of your kerbDemoMPG configuration to create a new MPG Policy for this configuration.
  2. In the "Configure Multi-Protocol Gateway Style Policy" panel, enter kerbDemoMPGPolicy for the "Policy Name" field.
  3. Under the Rule section, select Client to Server for the "Rule Direction". Then click the New Rule button.
  4. Double-click on the Match action (the diamond with an equal sign in the middle) and create a "Matching Rule" that matches all incoming client requests that are directed for the snoop application.
  5. Click the "+" sign next to "Matching Rule" combo box.
  6. In the resulting "Configure Matching Rule" panel, while in the Main tab, enter kerbDemoSnoopMatch for the Name field, as shown in Figure 9.
    Figure 9. Configure the Matching Rule name
    Configure Matching the Rule name
  7. Click on the Matching Rule tab of the "Configure Matching Rule" panel. Click on the Add button to create a new matching rule. Leave "Matching Type" set to URL and enter /snoop for the "URL Match" value, as shown in Figure 10.
    Figure 10. Create Matching Rule
    Create Matching Rule
  8. Click Apply to save these changes. Click Apply again in the "Configure Matching Rule" panel. Click Done in the "Configure a Match Action" panel to update this new matching rule. See Figure 11.
    Figure 11. Configure matching action
    Configure matching action

Define an AAA action

The AAA action will be defined next as part of this MPG Policy Rule. This is the most interesting set of configuration steps as it directly involves the Kerberos artifacts that you generated earlier.

  1. From the "Create rule:" section of the "Configure Multi-Protocol Gateway Style Policy" panel, click on the AAA icon and drag it to the rule line, as shown in Figure 12.
    Figure 12. Drag AAA onto the rule line
    Drag AAA onto the rule line
  2. Double-click on the newly positioned AAA icon to configure the AAA actions. On the resulting "Configure AAA Action" panel, first change the "Input" selection from (auto) to INPUT. Next change the "Output" value from (auto) to OUTPUT, as shown in Figure 13.
    Figure 13. Input and Output settings
    Input and Output settings
  3. Click on the "+" to the left of the "AAA policy" combo box to create a new AAA Policy object, as shown in Figure 14.
    Figure 14. AAA Policy Add button
    AAA Policy Add button
  4. In the "Configure an Access Control Policy" panel, enter kerbDemoAAAPolicy and click the Create button.
  5. On the next panel, check the HTTP Authentication Header checkbox under the "Define how to extract a user's identity ..." section. Click the Next button.
  6. Under the "Define how to authenticate the user" section of the next panel, check the Bind to Specified LDAP Server checkbox, as shown in Figure 15.
    Figure 15. Bind to Specified LDAP Server selection
    Bind to Specified LDAP Server selection
  7. Additional LDAP related configuration fields are added to the panel. Fill in these values as shown below:

    LDAP Load Balancer Group:<load balancer group of LDAP servers; default is "none">

    Host:<ip address or host name of LDAP server>

    Port:<LDAP port; default value is "389">

    SSL Proxy Profile:<name of ssl proxy profile; default is "none">

    LDAP Bind DN:<bind Distinguished Name (DN) that has permission to search LDAP directory>

    LDAP Bind Password: <bind DN password>

    LDAP Search Attribute:<default is "dn">

    LDAP Version:<default is "v2">

    LDAP Search for DN<default is "off">

    LDAP Prefix:<String prepended to username to form a DN to search for, default is "cn=">

    LDAP Suffix:<default is blank field>

    Use Auxiliary LDAP Attributes:<default is none>

  8. Once these values are appropriately filled in to match your LDAP environment, click the Next button, as shown in Figure 16.

    Notes:

    • The information required for these LDAP configuration fields are different for each customer, depending on each customer's specific LDAP environment. In this article, we have tried to use default values to make this demo setup as easy as possible. Some of the fields used in this example are not necessary when dealing with incoming basic authentication username and password attributes. For instance, in our AAA LDAP configuration, attributes such as "LDAP Bind DN" and "LDAP Bind Password" are not required and can be left empty since they are only applicable when dealing with WS-Security UsernameTokens.
    • In our demo scenario, the username and password received via the basic authentication header will instead be used to bind to LDAP and authenticate the user. If your clients were using soap messages and WS-Security elements, then different LDAP attribute values might be required. The primary message here is that this is a simplified configuration. Different environments might require significantly different values. It is advised that you work with your LDAP administrator when configuring for your specific LDAP environment.
    Figure 16. LDAP Server settings
    LDAP Server settings
  9. Click the Next button. On the "Define how to extract the resources" section of the next panel, click the URL Sent to Back End checkbox as shown in Figure 17, and click the Next button.
    Figure 17. Define how to extract the resources
    Define how to extract the resources
  10. On the "Define how to authorize a request" section of the next panel, leave the default radio button selection set for Allow Any Authenticated Client option, as shown in Figure 18. This indicates that any client that is successfully authenticated is authorized to access the backend server. Click the Next button.
    Figure 18. Define how to authorize a request
    Define how to authorize a request

    On the final panel of our AAA Access Control Policy, you will configure the Kerberos client and server principals.

  11. Under the "Choose any post processing" section of this panel, select the Generate a Kerberos SPNEGO token radio button option. This forces additional Kerberos related input fields to be added to the panel. Fill in the values as shown below:

    Kerberos Client Principal:HTTP/dpkerbclient.csupport.com@CSUPPORT.COM

    Kerberos Client Keytab:<upload the client keytab file previously generated on Domain Controller>

    Kerberos Server Principal: <server SPN> (HTTP/oc4102831681.csupport.com@CSUPPORT.COM in our example)

    Note: "CSUPPORT.COM" is the AD realm for our AD domain. Substitute it with your appropriate realm value, such as HTTP/dpkerbclient.test.com@TEST.COM .

  12. When uploading the keytab file, be sure to also select the Generate GSS-API Checksum in AP-REQ radio button in the file upload panel, as shown in Figure 19. If not, WebSphere Application Server might reject the token if it does not contain a checksum to verify that the token has not been modified.
    Figure 19. Enable Checksum generation
    Enable Checksum generation
  13. Click the Commit button to submit and apply this configuration, as shown in Figure 20.
    Figure 20. Kerberos configuration values
    Kerberos configuration values

    Notes:

    • The Kerberos Client Principal name is used to look up and identify the key entry in the Kerberos Client Keytab file. Even though there is only one SPN and Key entry in the client keytab file, the client principal specified in this field is used to match and extract this entry from the client keytab file. The client keytab entry, with the secret key, is needed because DataPower makes a request to the KDC server to get a Ticket Granting Ticket (TGT) for this client. The resulting TGT, sent back from the KDC, contains information inserted by the KDC that can only be decrypted with the client's key (KDC knows what the client's key is).
    • Once DataPower receives the TGT and correctly decrypts a session key out of the TGT (using the secret key from the client keytab), it uses the TGT to request a Service Ticket from the KDC to allow it to communicate with the snoop application. The Kerberos Server Principal is passed to the KDC to indicate what service that the Service Ticket is for. After DataPower receives this Service Ticket, it caches it and then uses it to create service tokens for outgoing requests to the snoop application (token sent in the HTTP header). The snoop application is configured for Kerberos authentication and can decrypt the service ticket, since it was encrypted in the KDC using the secret key for the specified Server Principal, and validate the identity of the user.
  14. Click on the Done button on the "Configure an Access Control Policy" panel, click Done on the "Configure AAA Action" panel, and then click the Apply Policy button on the "Configure Multi-Protocol Gateway Style Policy" panel. Then click the Close Window link on the "Configure Multi-Protocol Gateway Style Policy" panel (upper right-hand section of the panel) to close this panel and return to the main DataPower console panel, as shown in Figure 21.
    Figure 21. Applying and closing the MPG Style Policy
    Applying and closing the MPG Style Policy
  15. On the main "Configure Multi-Protocol Gateway" panel, click the Apply button to commit these changes and then save this configuration, as shown in Figure 22. You are now almost ready to test the new configuration.
    Figure 22. Apply updated configuration changes for MPG
    Apply updated configuration changes for MPG

Configuring the Kerberos KDC server

Before testing, you need to configure a KDC server for DataPower to communicate with.

  1. On the left side of the panel, expand the Objects folder and then expand the Crypto Configuration folder. Click on the Kerberos KDC Server object, as shown in Figure 23.
    Figure 23. Kerberos KDC Server under the Crypto configuration
    Kerberos KDC Server under the Crypto configuration
  2. In the "Configure Kerberos KDC Server" panel, click the Add button to add a new KDC server entry. Enter a name for your KDC server (this can be anything meaningful to you) and then enter the realm name in the "Kerberos realm name" field and the host name or IP address of the KDC server in the "Kerberos KDC Server" field. You can click the Ping Remote button to ensure that you can contact the KDC server.

    Note: The Kerberos realm name must match the realm name used in the client and server SPN values defined earlier in your AAA Post Processing action, such as CSUPPORT.COM. Case sensitivity is also important.

  3. To prevent possible errors related to Kerberos token sizes, turn on the "Use TCP" radio button. The "Server Port Number" field typically remains as the default value (88). Click the Apply button to create this new KDC Server object, as shown in Figure 24. Finally, save the configuration.
    Figure 24. Configure the Kerberos KDC Server
    Configure the Kerberos KDC Server

Testing the DataPower MPG Kerberos configuration

You can now run a test to determine if your new MPG configuration is set up properly. To make testing as easy as possible to set up, use the "curl" utility to submit your requests to DataPower.

  1. Issue the curl command to simulate a client browser sending a request to DataPower targeted for the snoop application:
    curl -v --basic -u "mjmwasuser2:passw0rd" 
     http://l2dp1.rtp.raleigh.ibm.com:50000/snoop

    In the command above, you are using the --basic -u <username:password> option to send a basic authentication header in the HTTP request, using a valid LDAP username and password. This is the user ID and password that authenticates the client against LDAP in your AAA policy. If the user ID is successfully authenticated, then DataPower generates a Kerberos service ticket and sends a request to the snoop application with this token included as a HTTP header. If everything works correctly and the Kerberos token is properly authenticated by the backend Application Server, then the response looks similar the snippets shown in Listing 1.

    Listing 1. Sample curl command to test the Kerberos configuration
    $ curl -v  -u "mjmwasuser2:wasUs3r2" http://l2dp1.rtp.raleigh.ibm.com:50000/snoop
    * About to connect() to l2dp1.rtp.raleigh.ibm.com port 50000 (#0)
    *   Trying 9.42.125.160... connected
    * Connected to l2dp1.rtp.raleigh.ibm.com (9.42.125.160) port 50000 (#0)
    * Server auth using Basic with user 'mjmwasuser2'
    > GET /snoop HTTP/1.1
    > Authorization: Basic bWptd2FzdXNlcjI6d2FzVXMzcjI=
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 
    NSS/3.13.1.0 zlib/1.2.3 libidn/1.18 libssh2/1.2.2
    > Host: l2dp1.rtp.raleigh.ibm.com:50000
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < X-Backside-Transport: OK OK
    < Connection: Keep-Alive
    < Transfer-Encoding: chunked
    ...
    ...
    ...
    <tr><td>javax.servlet.context.tempdir</td><td>/opt/ibm/
    SDP/runtimes/base_v7/profiles/WTE_APPSRV71/temp/localhostNode01/server1/
    DefaultApplication/DefaultWebApplication.war</td></tr>
    <tr><td>com.ibm.websphere.servlet.event.ServletContextEventSource
    </td><td>com.ibm.ws.webcontainer.webapp.WebAppEventSource@2e5f2e5f
    </td></tr>
    <tr><td>com.ibm.wsspi.portletcontainer</td><td>
    com.ibm.ws.portletcontainer.pcinvoker.PortletContainerImpl@7c627c62</td></tr>
    </table><BR><BR>
    </body></html>
    * Connection #0 to host l2dp1.rtp.raleigh.ibm.com left intact
    * Closing connection #0
    $

    If the HTML content from the response is opened with a browser, it appears similar to Figure 25.

    Figure 25. Snoop application response
    Snoop application response

Probe analysis

A tool that is helpful in analyzing traffic flow through DataPower and confirming correct behavior is the "DataPower Probe" utility. As your final activity in testing your Kerberos MPG configuration, you will enable Probe for this configuration and then run the "curl" test one more time. To enable and validate a test using the Probe tool, do the following:

  1. Go to the main MPG panel for the kerbDemoMPG configuration and click the Show Probe link, as shown in Figure 26.
    Figure 26. Show Probe link
    Show Probe link
  2. In the Probe panel, click the Enable Probe button to enable a probe capture, as shown in Figure 27.
    Figure 27. Enable Probe button
    Enable Probe button
  3. Run the curl test again as described above. After this test is run, go back to the Probe panel and click the Refresh button. You now see a new Probe record displayed as seen in Figure 28. The Probe record is preceded with a magnifying glass icon.
    Figure 28. Captured Probe Record
    Captured Probe Record
  4. Click on the magnifying glass icon to view the Probe record. From the resulting panel, click on the AAA icon (the square AAA icon shown in Figure 29). If the request ran successfully, you see two records related to the AAA processing – the "ldap-authen" record and the "get-kerberos-apreq" record. Both of these records have a clickable "(show nodeset)" link for both the request and response. A missing request or response link for either of these records indicates a problem. See Figure 29.
    Figure 29. AAA Probe execution trace
    AAA Probe execution trace
  5. To verify that a valid Kerberos token was generated, click on the (show nodeset) link on this panel. You see an <apreq> token element as seen in Figure 30. The <spnego-apreq-base64> sub-element, which is contained in this element, is passed to the backend server as an HTTP header (Figure 30).
    Figure 30. Generated Kerberos token
    Generated Kerberos token
  6. Finally, back on the Probe panel, click on the magnifying icon that comes after the AAA action icon. From here, click on the Headers tab. Verify that you see the "Authorization" header with the contents from the previously viewed <spnego-apreq-base64> sub-element, as part of the header, as shown in Figure 31. This provides confirmation that the Kerberos related processing succeeded and that a Kerberos token was generated for the outgoing request to the backend server.
  7. If problems are encountered, go back to the main Probe panel where you Enabled Probe (see Figure 27 or Figure 28) and click on the View Log button to examine the log messages related to the failed test. If necessary, go to the Troubleshooting Panel in DataPower and set the Log Level to debug to allow for more detailed log messages to be generated. Then repeat your tests again and view the generated log messages.
    Figure 31. HTTP Authorization header
    HTTP Authorization header

Troubleshooting tips

This section provides some common problems you might encounter when setting up DataPower for Kerberos authentication. Table 1 shows the associated resolutions for each of these problems.

Notes:

  • The Debug Log Level can be set by navigating to Troubleshooting > Logging to increase the logging level to "Debug-Level".
  • The CWSPN0011E error mentioned in Table 1 almost always requires additional tracing described in the MustGather document, Problems with Spnego.
Table 1. Troubleshooting common problems
Problem Symptom Resolution
Invalid Client SPN is used for the Kerberos Client Principal in DataPower AAA Post Processing. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Kerberos error in post processing: Client principal 'HTTP/BADdpkerbclient.csupport.com@CSUPPORT.COM' not found in Kerberos KDC database
Use the correct SPN for the Kerberos Client Principal
Invalid Server SPN is used for the Kerberos Server Principal in DataPower AAA Post Processing. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Kerberos error in post processing: Server principal 'HTTP/BADoc4102831681.csupport.com@CSUPPORT.COM' not found in Kerberos KDC database
Use the correct SPN for the Kerberos Server Principal.
Realm name not included in Client or Server SPN in DataPower AAA Post Processing. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Kerberos error in post processing: Invalid Kerberos principal name: 'HTTP/dpkerbclient.csupport.com'
Ensure the Realm name is included in the Kerberos Client Principal and Kerberos Server Principal (–for example, HTTP/dpkerbclient.csupport.com@CSUPPORT.COM).
Wrong Client SPN used for Kerberos Client Principal in DataPower AAA Post Processing. In this case, the Client SPN is a valid SPN in the KDC, but it is not the SPN that matches the SPN/key-entry in the client keytab file. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Kerberos error in post processing: Kerberos KDC 'CSUPPORTKDC' required preauthentication that could not be provided
Ensure the SPN used in the Kerberos Client Principal field matches the SPN in the client keytab file.
Wrong Server SPN used for Kerberos Server Principal in DataPower AAA Post Processing. In this case, the Server SPN is a valid SPN in the KDC, but it is not the SPN that is associated with the backend server that client request is ultimately targeted for. This causes the backend server to receive a Service Ticket token that it cannot decrypt and typically results in an error being logged by the backend server and an error response is returned. A token is generated by DataPower and can be seen in the Probe. For a WebSphere Application Server targeted backend server, the following is an error message that might be observed in the Application Server trace log in this circumstance:
0000000f Context E com.ibm.ws.security.spnego.Context begin CWSPN0011E: A non-valid SPNEGO token has been encountered while authenticating a HttpServletRequest: 0000: a1143012 a0030a01 01a10b06 092a8648 ..0. .... .... .*.H
Ensure the SPN used in the Kerberos Server Principal field is the correct SPN for that service. The WebSphere Application Server administrator can issue a "klist" command against the keytab files used by Application Server to verify what the service SPN value is.
Checksum option is not turned on in DataPower AAA Post Processing. If the backend server is configured to expect a checksum value in the Service Ticket token, this typically results in an error being logged by the backend server and an error response is returned. A token is generated by DataPower and can be seen in the Probe. For a WebSphere Application Server targeted backend server, the following is an error message that might be observed in the Application Server trace log in this circumstance:
0000000f Context E com.ibm.ws.security.spnego.Context begin CWSPN0011E: A non-valid SPNEGO token has been encountered while authenticating a HttpServletRequest: 0000: a1143012 a0030a01 01a10b06 092a8648 ..0. .... .... .*.H
Ensure the "Generate GSS-API Checksum in the "AP-REQ" radio button in the Kerberos Client Keytab configuration panel is checked (this is in the AAA configuration).
An older or different Key Version Number (kvno) is associated with the SPN in the client keytab file than what exists in the KDC for that SPN.
Symptom: Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Cannot parse file for Kerberos keytab 'dpkerbclientKeytab'
Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Cannot parse file for Kerberos keytab 'dpkerbclientKeytab'
Ensure the kvno in the Client keytab file matches the kvno associated with that SPN in the KDC. Use the "ldifde" command on the KDC Domain Controller machine to determine what kvno value is used by the KDC for the given SPN. Then use the "klist" utility on a Linux machine to determine the kvno in the keytab file (klist -k <keytab file>). If they are different, create a new keytab file to ensure its kvno matches the kvno used by the KDC.
When invoking the ktpass command to create a keytab file and explicitly specifying the Key Version Number (kvno) using the "-kvno" parameter, the kvno in the keytab file still does not match the kvno in the KDC. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Cannot parse file for Kerberos keytab 'dpkerbclientKeytab'
It appears that some versions of ktpass, if not all versions, force the kvno to be incremented in the KDC each time the keytab file is generated for a given SPN. If the "-kvno" parameter is specified on the command line, it only sets the kvno in the keytab file to the specified value. The kvno in the KDC increments to the next higher value. Many times users will use the "ldifde" command on the Domain Controller to get the current kvno value in the KDC for a given SPN, and then invoke the ktpass command to create a new keytab file that matches that kvno by using the "-kvno" parameter. This does not work as the KDC's kvno for that SPN is incremented as a result of issuing the ktpass command. Instead, simply issue the ktpass command without the "-kvno" parameter and the resulting keytab file has the same
kvno value as the KDC.
The Kerberos KDC Server object, under Objects > Crypto Configuration, was not created, or its "Kerberos realm name" value did not match the realm contained within the Kerberos Principal value in the AAA Post Processing panel. Case sensitivity is relevant when matching these realm values. Debug level message seen in DataPower error log:
mpgw (kerbDemoMPG): Kerberos KDC for realm 'CSUPPORT.COM' not found
Ensure the realm specified in the Kerberos KDC Server object matches the realm specified in the Kerberos Principal Names in the AAA Post Processing panel.
When monitoring network traffic while testing the DataPower Kerberos configuration, there appears to be no network communication between DataPower and the KDC server. No Kerberos-related IP packets are seen flowing between DataPower and the KDC server when capturing network packets during testing of the Kerberos configuration. However, DataPower is still able to generate Kerberos tokens destined for the backend server. DataPower caches Service tickets sent from the KDC, so it does not request a new Service Ticket for each request. No resolution is needed as this is a normal and correct behavior within DataPower.

Conclusion

This article demonstrated how to set up a Multi-Protocol Gateway configuration using the DataPower WebUI, which allowed non-Kerberos, authenticated clients to connect to a backend WebSphere Application Server web application that only accepts requests from Kerberos authenticated clients. As part of this demonstration, you learned how to authenticate your clients using a different authentication method, and then submit all requests to the backend server under a single Kerberos principal name.

You also learned how to generate the necessary Kerberos artifacts that your configuration required, and where those artifacts are used and their purpose. Finally, you also looked at a convenient way to test out your MPG configuration using the "curl" utility and how to troubleshoot our configuration if things do not work out successfully from the start.

In our next article, we look at how to generate Kerberos tokens in a more programmatic fashion by using the DataPower customer stylesheet dp:get-kerberos-apreq method. We also discuss why you would use this approach and what advantages and disadvantages it has over the approach we demonstrated in this article.


IBM Support

If you need further assistance, collect the following MustGather information and contact IBM Support:

Resources

Learn

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=826350
ArticleTitle=Configuring a WebSphere DataPower Kerberos-secured backend server, Part 1: Using the DataPower Web Graphical User Interface
publish-date=10182013