In this second of this 2-part series, you will again work with a solution that has a set of clients that need to connect to a web application on the backend server. This web application, the sample "snoop" application, is still secured by Kerberos authentication. Also similar to the scenario in the first article, the incoming clients are not authenticated in DataPower via Kerberos. Instead, basic authentication and a Lightweight Directory Access Protocol (LDAP) server are used to authenticate to the DataPower appliance.
For this new scenario, you will setup a Multi-Protocol Gateway (MPGW) to accept incoming client requests as HTTP GET requests, authenticate and authorize the clients based on their incoming credentials, and then submit the client requests to the backend server using a Kerberos token to authenticate with the backend server. This is similar to what was done in the first article. In this scenario, however, you will use a more dynamic approach to create the Kerberos ticket. A sample DataPower configuration and a sample custom stylesheet are provided in the Downloads section of this article.
Note that DataPower V6.0.0 supports constrained Kerberos delegation. This article does not describe that feature.
Scenario from the previous article
The last article discussed the steps needed to set up a Kerberos configuration in DataPower in a static fashion using the DataPower Web Graphical User Interface. We described how to create a Multi-Protocol Gateway (MPGW) configuration that allowed incoming clients to access a web application on a customer's backend server. The application on the backend server was secured via Kerberos authentication. In that static DataPower configuration, all of the client requests were first authenticated and authorized by DataPower by extracting the credentials from the incoming HTTP Basic Authentication Header and verifying them against a Lightweight Directory Access Protocol (LDAP) server. These client requests were then forwarded to the backend server application after DataPower injected a Kerberos ticket into the request. In this static configuration, the Kerberos ticket was generated using the single DataPower ID registered on the KDC. The actual client user ID was not used to generate the Kerberos ticket in this scenario.
As was mentioned in the first article, sending all user requests to the backend server under a single Kerberos user ID is perfectly fine if the the backend web application does not need to obtain the originating client user ID from the Kerberos token. In the static configuration scenario, the client has passed the authentication and authorization screening and is, therefore, considered a legitimate user to access the web application.
If the client user ID was required in this solution, it could have been passed into the backend server through other potential techniques, such as using a HTTP request parameter or a SOAP element. However, there may be other solutions with a requirement for the client ID to be passed to the backend application via the Kerberos ticket. In this article, we will address this scenario and demonstrate how to use custom stylesheets to dynamically create a Kerberos ticket with the client ID.
Dynamic solution scenario
The scenario that you will work with in this second article has a set of clients that need to connect to a web application on the customer's backend server. This web application, the sample "snoop" application, is still secured by Kerberos authentication. Also similar to the scenario in the first article, the incoming clients are not authenticated in DataPower via Kerberos. Instead, basic authentication and a Lightweight Directory Access Protocol (LDAP) are used to authenticate to our DataPower appliance.
For this new scenario, we will set up a Multi-Protocol Gateway (MPGW) to accept incoming client requests as HTTP GET requests, authenticate and authorize the clients based on their incoming credentials, and then submit the client requests to the backend server using a Kerberos token to authenticate with the backend server. This is similar to what was done in the first article. In this second scenario, however, you will use a dynamic approach to create the Kerberos ticket.
Kerberos interaction in this dynamic scenario
The DataPower MPGW in the first article was configured to use a static Client Keytab file that allowed DataPower to generate Kerberos tickets using the Kerberos user ID defined in that keytab file. Because of this, all of the client requests were mapped to a single Kerberos ID, which used to be Kerberos Principal name for DataPower that is configured in the KDC. This required the authorization filtering steps to be performed in DataPower before allowing a client to access the web application. The backend server did not receive the actual client user ID.
In the new scenario, you will configure the DataPower MPGW to generate a Kerberos ticket using the actual client ID as the Kerberos principal name. To do this, the MPGW extracts the client ID and password from the basic authentication credentials. The user ID and password are also stored in the domain's Active Directory (AD) database and the password serves as the secret key by the Key Distribution Center (KDC) when it generates Kerberos tokens. This is the same secret key that is stored in a keytab file when a keytab file is generated for a Service Principal Name (SPN). Therefore, DataPower communicates with the Key Distribution Center (KDC) and requests a service ticket from the KDC for a given client ID using the extracted password. One key requirement for this new approach is the need for all the clients to have an ID (Principal) in the Kerberos KDC realm. This was not a requirement in the first article.
An overview of this dynamic approach is shown in Figure 1.
Figure 1. Overview of the dynamic solution scenario
An advantage of this approach is that a Kerberos keytab file does not need to be imported into the DataPower MPGW configuration. Since access to the secret key is achieved dynamically by the extracting it from the incoming client request, it does not need to be extracted from a pre-imported, static keytab file. This helps to simplify the Kerberos keytab administration.
A disadvantage to this approach is that it requires a more complicated, programmatic configuration. A DataPower extension function is needed to communicate with the KDC, pass in the required parameters, and request or receive a service ticket.
The good news is that even though this MPGW configuration requires a programmatic approach, the custom XLST transform is not difficult to write or understand. There is a good reference manual that provides details on the various extension functions and example snippets showing how the extension functions are used. This reference was initially produced for version 3.8.1 of DataPower, but it is still a useful guide in understanding how to write XSLT stylesheets.
Another notable disadvantage to this approach, as we inferred earlier, is the need to ensure that every client has an ID in the KDC realm. In a Windows® Active Directory (AD) environment, as used in this scenario, this may not be a significant disadvantage if all users already exist in the AD. The Microsoft® KDC uses the AD directory database, so there is not an extra step needed to ensure that the KDC has the user Principal. In other types of Kerberos environments, this may not be as easy to administer.
Kerberos and domain controller tasks
You do not need to create a client Service Principal Name (SPN), as required in the first article. You will, instead, use the User Principal Names (UPN) that are associated with all of the Active Directory (AD) user accounts. These same userids are then used for both LDAP authentication and for identity in the Kerberos tickets.
Create Active Directory client accounts
For our sample scenario, you will create two client IDs in the AD repository. Typically, you either expect that these IDs already exist in the directory, or you have to create user IDs for all the clients that will be accessing the web application through DataPower.
- Set up the first client user ID in the AD. In the AD Users console,
right-click the Users folder and choose New
> User. Enter
democlient1in 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
- 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
Figure 3. New AD user options
- Click the Finish button to complete the creation of
this new user account. Set up the second client user ID in the AD.
Perform the instructions in Steps 1 through 3, but use
democlient2for the "Full name" field and "User logon name" field.
Now run a Windows OS based utility command on the Domain Controller server to view the attributes related to the newly created user IDs to verify the value of the UPN stored in the AD. The command exports the objects from the AD repository and writes them to a specified file.
- Open a DOS command window on the Domain controller machine and issue
the following command (substitute your appropriate base distinguished
"DC=support,DC=com"for the one shown below. See Figure 4.
Figure 4. ldifde command execution
- Open the c:\temp\ldapData.txt file and search for the
new "demoClient1" user ID that was created in Step 2. You see
"userPrincipalName" for this user ID. This is the UPN value you will
use when you create the client Kerberos ticket in DataPower. See
Figure 5. demoClient1 AD attributes
Kerberos keytab file – server application
The only other task that you will perform on the Domain Controller is to verify that the SPN for the backend server application that exists in the KDC. On WebSphere Application Server, where the snoop application is hosted, the administrator has already set up a user ID and an SPN to be used as the Server SPN. The administrator also created a keytab file for that server SPN account. This keytab file is uploaded to Application Server to allow the decryption of service tickets that are sent to it.
As was the case in the first article, you need to obtain this SPN value
HTTP/oc4102831681.csupport.com is the SPN for the demo
solution) that was set up for Application Server. Once you find out what
the user ID account name is associated with the server SPN, you can issue
the following command to verify that this account is still active:
setspn -l <userid associated with the server application SPN>
You see the following type of output from this command. In our example, the account name for the server SPN, HTTP/oc4102831681.csupport.com, is "waskerb".
DataPower related tasks
You can create a Multi-Protocol Gateway (MPGW) configuration that allows your clients to connect to your backend web application (the snoop application) using a Kerberos ticket associated with the client's UPN. In this configuration, clients will submit HTTP GET requests to DataPower with a basic authentication string that contains the client user ID and password. DataPower accepts a client request, authenticate the user in LDAP, and creates a Kerberos ticket based on the client's UPN. This Kerberos ticket authenticates the backend server and provides access to the snoop application. The response from the snoop application is passed back to the client. Since the client user ID is passed in the Kerberos ticket, the snoop application can generate information that identifies the name of the actual end client. This is a key difference from the first article where the principal name displayed in the snoop output was always the name associated with the single client keytab file that is statically configured in DataPower.
Create the Multi-Protocol Gateway
- Log into the DataPower console. In the "default" domain, create a new application domain called kerbDemo. If you have already completed the DataPower configuration for the first article of this series, you should already have a kerbDemo domain and do not need to create this domain.
- Switch to this new kerbDemo domain and click on the Multi-Protocol Gateway (MPGW) icon.
- In the MPGW panel, click the Add button. Create a new
MPGW configuration called
kerbDemo2MPGby typing this into the "Multi-Protocol Gateway Name" field. Leave the "Type" field set to static-backend.
Define the front side handler settings
Define a front side handler to accept a HTTP GET requests on port "50008" (this is an arbitrary port we have selected for incoming requests), and ignore all requests except those targeted for the "snoop" application.
- 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 MPGW panel, as shown in Figure 6.
Figure 6. Selecting the Front Side Protocol Handler type
- In the resulting "Configure HTTP Front Side Handler" panel, type in
kerbDemo2FSHin the "Name" field, type
50008for the "Port Number" field, and check the GET method checkbox below, as shown in Figure 7. Leave all the other fields alone and click the Apply button.
Figure 7. Front Side Handler settings
- 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 the other fields or attributes set to their defaults.
Define the back side settings
- For the back side settings, enter the URL required to access the
WebSphere Application Server snoop application. In our case, it was
- 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 the
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
Define the Multi-Protocol Gateway policy
Similar to the first article, you will now define the MPGW Policy. The policy authenticates the incoming clients against the LDAP server using the client provided basic authentication credentials. As part of this policy, however, you will be writing and using a custom XSLT stylesheet transform object that is invoked each time a client request is processed. This stylesheet uses one of the DataPower provided XSLT functions to make a call to the KDC server and creates a Kerberos ticket, using the client's user ID and password credentials that were passed in with the client's basic authentication string. This allows DataPower to propagate the actual client's user ID to the backend server in the Kerberos ticket.
- Click the "+" sign under the "Multi-Protocol Gateway Policy" section of your kerbDemo2MPG configuration to create a new MPGW Policy for this configuration.
- In the "Configure Multi-Protocol Gateway Style Policy" panel, enter
kerbDemo2MPGPolicyfor the "Policy Name" field.
- Under the Rule section, select Client to Server for
the "Rule Direction". Then click the New Rule button.
Your policy now looks similar to what is shown in Figure 9.
Figure 9. Initial MPGW Policy panel
- 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.
- Click the "+" sign next to "Matching Rule" combo box.
- In the resulting "Configure Matching Rule" panel, while in the
Main tab, enter
kerbDemo2SnoopMatchfor the Name field, as shown in Figure 10.
Figure 10. Configure the matching rule name
- 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
/snoopfor the "URL Match" value, as shown in Figure 11.
Figure 11. Create a matching rule
- 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 12.
Figure 12. Configure matching action
Define an AAA action
Now create your security action where you will be writing your custom XSLT transform code. You will first step through the preliminary panels that are a part of the AAA action to configure the authentication and authorization behavior for the incoming client requests.
- 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 13.
Figure 13. Drag AAA onto the rule line
- 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 14.
Figure 14. Input and output settings
- Click on the "+" to the left of the "AAA policy" combo box to create a
new AAA Policy object, as shown in Figure 15.
Figure 15. AAA Policy Add button
- In the "Configure an Access Control Policy" panel, enter
kerbDemo2AAAPolicyand click the Create button.
- On the next panel, check the HTTP Authentication
Header checkbox under the "Define how to extract a user's
identity ..." section as shown in Figure 16. Click the
Figure 16. AAA Policy Add button
- 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 17.
Figure 17. Bind to specified LDAP server selection
- 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>
- Once these values are appropriately filled in to match your LDAP environment, click the Next button. In this demo scenario, the incoming user ID and password were used to bind to the LDAP server and authenticate the user, so only the LDAP IP address and port were required (everything else was defaulted). This is a very simplified configuration. You will need to configure your LDAP server in a way that is appropriate for your security environment. See Figure 18.
- One important clarification to mention here is that, since you will be
authenticating the user ID and password as part of the Kerberos ticket
generation, this step of authenticating with the LDAP server is
redundant. We have included this step as an example of how to perform
LDAP authentication, but it is not a necessary step for this scenario.
Figure 18. LDAP server settings
- Click the Next button. On the "Define how to extract
the resources" section of the next panel, click the URL sent
to backend checkbox as shown in Figure 19, and click the
Figure 19. Define how to extract the resources
- On the "Define how to authorize a request" section of the next panel,
leave the default radio button selection set for the Allow any
authenticated client option, as shown in Figure 20. This
indicates that any client that is successfully authenticated is
authorized to access the backend server. Click the
Figure 20. Define how to authorize a request
On the final panel of the AAA Access Control Policy, you will configure the policy to use a custom XSLT processing stylesheet. In this stylesheet, you will write code to programmatically perform the following processing steps:
- Extract the user ID and password from the incoming basic authentication credentials and place these values in variables.
- Populate two variables with the Server SPN (SPN is the backend web application, which has to be hardcoded), and the Client SPN, using the incoming user ID (UPN) as part of the Client SPN.
- Generate a Kerberos token by calling the DataPower provided
dp:get-kerberos-apreq() extension function. The Client SPN,
the client password (this is also the client's secret key from
the KDC's perspective), and the Server SPN is used as
parameters for this function call. The returned token from the
KDC contains the incoming client user ID since you specified
the UPN for your token request.
Note: In this example, we are also setting an optional parameter for the dp:get-kerberos-apreq() method to turn on the "generateGssChecksum" option. This forces a checksum to be generated for the Kerberos token. This checksum is required if interacting with more current versions of WebSphere Application Server.
- Populate a variable to hold the value of the Kerberos token. Extract the necessary string from the token returned from the previous dp:get-kerberos-apreq() call to populate this variable.
- Add this header as an "Authorization" header to the outgoing request to the backend server.
When the client request is sent to the backend server, it contains a Kerberos token associated with the actual client user ID. This allows the backend server to authenticate the Kerberos token and identifies the user who made the request. As mentioned before, this is different from the first article of the series, where all the requests are sent to the backend server with one common or shared user ID (user ID associated with the Client keytab file imported into DataPower).
- Create a new file called kerbDemo2Custom.xsl. Add the
code shown in Listing 1 to the file and save this file to a temporary
directory. You are looking at the Probe data later in this article to
get more clarification on the logic in this stylesheet.
Listing 1. KerbDemo2Custom.xsl
- Under the "Choose any post processing" section of this panel, click
the on radio button for the "Run Custom Post
Processing Stylesheet" option. Then click the Upload
button as shown in Figure 21.
Figure 21. Run Custom Post Processing Stylesheet section
- In the "Upload File to Directory" panel, browse to the directory where
the "kerbDemo2Custom.xsl" resides, highlight it, click
Open, and click the Upload
button. See Figure 22.
Figure 22. Upload XSL file dialog
- Click the Commit button to submit and apply this configuration.
- 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 23.
Figure 23. Applying and closing the MPGW Style Policy
- 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 24. You are almost ready
to test the new configuration.
Figure 24. Applying and closing the MPGW Style Policy
Configuring the Kerberos KDC server object on DataPower
Like the demo scenario in the first article of this series, this step is required. If not already done, you need to configure a KDC server for communication with DataPower.
- 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 25.
Figure 25. Kerberos KDC Server under the crypto configuration
- 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 important.
- To prevent possible errors related to the 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 26. Finally, save the configuration.
Figure 26. Configure the Kerberos KDC Server
Testing the dynamic scenario
You are now at the stage where you can test the MGP configuration and ensure that the client making the request through DataPower can connect to the backend server with the dynamically generated Kerberos service ticket. As in the first article, you again use the "curl" utility to submit the test requests to DataPower. You use the exact same command used in the first article, but you use the port number associated with this new MPGW configuration instead. You also issue the command using the two user IDs that were setup in the Create Active Directory Client Accounts section.
- Issue the following curl command to simulate a client browser sending
a request to DataPower to access the backend snoop application. The
sample results are shown in Listing 2.
curl -v --basic -u "democlient1:d3m0Passw0rd" http://18.104.22.168:50008/snoop
Listing 2. Sample results from the curl command to test the Kerberos configuration
If this HTML content from the response is opened with a browser, it appears similar to Figure 27. As you can see in this response data, the "Remote user" value is set to value of the client who made the request. This is a key difference from the scenario in the first article, where the "Remote user" value was always the user ID associated with the client keytab file that was imported into DataPower.
Figure 27. Snoop application response with client user ID
To help clarify what is going on in the custom stylesheet logic, you can enable the DataPower Probe for this MPGW configuration as was discussed in the previous article. After you do this and run a test, you can review the probe output and click on the AAA icon. You see something similar to Figure 28.
Figure 28. AAA Probe execution trace
If you click on the (show nodeset) link on this panel, you can view the
<apreq> element that is generated by
dp:get-kerberos-apreq function that you called in your custom stylesheet.
Observe that the
within this token. This is the information that your custom stylesheet
extracts from the token and places into a temporary variable. See Figure
Figure 29. Generated Kerberos token
Finally, if you go back to the Probe panel and click on the magnifying glass icon that is located after the AAA action icon, and then click on the Headers tab of the resulting panel, you see the "Authorization" header is one of the headers included in the HTTP request. This is the header that was inserted by your custom stylesheet. Also notice the value of this header contains "Negotiate", followed by a string from the "<spnego-apreq-base64>" sub-element. This matches the logic in the stylesheet. See Figure 30. Hopefully, this review helps to reinforce your understanding of the logic in your custom stylesheet.
Figure 30. HTTP Authorization header
In addition to the troubleshooting tips from the first article, there are a few additional problems that you may encounter when developing this solution that uses a custom XSLT stylesheet.
Table 1. Troubleshooting tips
|Invalid user ID is used by the client in the Basic Authentication string when submitting requests to DataPower.|| Debug the level messages seen in the DataPower error log:||Verify that the user ID is a valid user in the Active Directory. If not, use a valid user ID. Make sure that principals for all the client users of the web application are created in the KDC.|
|Invalid user ID password is used by the client in the Basic Authentication string when submitting requests to DataPower.|| Debug the level message seen in the DataPower error log:||Use the correct password for the given user ID.|
|Syntax error in the custom XSLT stylesheet.|| Debug the level message seen in the DataPower error log:||Review the XSL file that was uploaded to DataPower and correct the code line or lines specified in the error message.|
This article demonstrated how to set up a Multi-Protocol Gateway configuration and how to generate Kerberos tokens in a more programmatic fashion by using the DataPower custom stylesheet dp:get-kerberos-apreq method. In other words, you learned how to authenticate by using a client user ID and password, and then submitted requests to the backend server using the dynamically generated Kerberos principal name.
Though the dynamic approach required more upfront configuration and programming, the advantage of this custom stylesheet approach was that a Kerberos keytab file no longer needed to be imported into the DataPower MPGW configuration. Since access to the secret key was achieved dynamically by the extracting it from the incoming client request, it did not have to be extracted from a pre-imported, static keytab file, which helped to simplify the Kerberos keytab administration.
Since the client user ID was propagated in the Kerberos ticket, the snoop application generated information that identified the name of the actual end client. This was the main difference from the first article, where the principal name displayed in the snoop output was always the name associated with the client keytab file.
You also learned how to generate the necessary Kerberos artifacts, where those artifacts are used and their purpose. Finally, you looked at a convenient way to test your MPGW configuration using the "curl" utility and reviewed how to troubleshoot your configuration.
If you need further assistance, collect the following MustGather information and contact IBM Support:
- From DataPower: Collecting WebSphere DataPower SOA Appliance Security and AAA Information
- If the backend server is WebSphere: Problems with Spnego
- Rewriting SOAPAction headers with WebSphere DataPower SOA Appliances
- Configuring a WebSphere DataPower Kerberos-secured backend server, Part 1: Using the DataPower Web Graphical User Interface
- WebSphere DataPower SOA Appliances V4.0.2 Information Center: set-http-request-header
- Using DataPower XSLT extension to add custom headers
- developerWorks WebSphere DataPower zone
- developerWorks WebSphere DataPower discussion forum
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.