Using DataPower with Tivoli Federated Identity Manager to support OAuth 2.0

Content

Introduction

At the last step of the OAuth protocol pattern, the OAuth client requests access to the desired resource directly from the server hosting that resource. The entire OAuth protocol exists to support this request, providing a secure method for clients to gain access to resources owned by someone else. For example, John wants to use some of Fred's photos for a project. John uses his graphics application (the OAuth client) to get access to Fred's photos (the resource server) that uses permission (in the form of an OAuth access token) granted by Fred (the resource owner). John's client application obtains the access token from a Tivoli Federated Identity Manager authorization server.

Figure 1. OAuth protocol exchange with Federated Identity Management and DataPower

The resource server verifies the OAuth access token before returning the photos requested by the client. However, this consumes server resources and requires configuration maintenance. The access verification can be done in the DMZ, but it is not secure to put the resource server in the DMZ. By placing a DataPower appliance in front of the resource server, all token handling and verification are done by the appliance rather than the server. This way, the DataPower device is positioned in the DMZ and becomes the OAuth resource server enforcement point.

When DataPower acts as an enforcement point for the resource server, it verifies the access token. DataPower only allows the request to the backend resource server if the access token is valid. To verify the token, the DataPower device contacts the Federated Identity Management server directly. The supported version of Federated Identity Management is V6.2.2 or later.

This article presents steps to configure the DataPower device as the enforcement point. In order to reproduce this configuration in your own environment, you need to have an instance of the Federated Identity Management server running and accessible on your network.

Register the OAuth client in Federated Identity Management

Before configuring the DataPower device, it is necessary to set up and configure the Federated Identity Management server. The complete set of steps for accomplishing this task is beyond the scope of this article. Figure 2 shows some of the key values held in Federated Identity Management.

Figure 2. Federated Identity Management OAuth client configuration

Note the values entered for Client Identifier and Client Shared Secret, shown at the bottom of the image in Figure 2. These values are used to identify the DataPower device when it contacts the Federated Identity Management server.

All remaining procedures take place on the DataPower device.

In order to shorten and simplify the procedures shown in this article, the configuration and artifacts needed to create an SSL Proxy Profile must first be imported into the DataPower device you are using for these steps. The zip files containing the information you need are provided with this article. Download both files and extract the two crypto key files from the OAuth-TFIM-SSLProfile-crypto.zip file.

1. To import and activate the SSL Proxy Profile, click the Import Configuration icon on the Control Panel. The Import Configuration panel appears as shown in Figure 3.

   Figure 3. Import Configuration panel

2. Click Browse and select the file OAuth-TFIM-SSLProfile-base.zip on your local filesystem.
3. Click Next. The device displays the contents of the zipped configuration file as shown in Figure 4.

   Figure 4. Configuration to Import

4. Scroll down and click Import. The device displays the results.
5. Click Done.
6. Click the Keys & Certs Management icon on the Control Panel.
7. Click Keys on the page that appears. A list of keys appears, two of which are in red.
8. Click oauth-tfim-tep. The Configure Crypto Key configuration panel appears.
9. Upload the file oauth-tfim-tep-privkey.pem from the zip file as shown in Figure 5.

   Figure 5. Crypto Key configuration

10. Click Apply. The object transitions to the "Up" state.
11. Type cert in the navigation pane Search box and click Crypto Certificate. A list of certificate objects appears.
12. Click oauth-tfim-tep (appears in red letters).
13. Upload the oauth-tfim-tep-sscert.pem file as shown in Figure 6.

    Figure 6. Crypto Certificate object

14. Click Apply. The object transitions to the "Up" state.
15. Type SSL in the Search box. Click SSL Proxy Profile. A list of SSL Proxy Profile objects appears. Two profiles marked "new" appear in the Up state as shown in Figure 7.

    Figure 7. SSL Proxy Profile listing

At this point, you need to upload a stylesheet to the device:

1. Download the provided bearer.xsl stylesheet to your local drive.
2. Click Control Panel at the top of the navigation pane.
3. Click the File Management icon.
4. Click Actions alongside the local folder and select Upload.
5. Upload the bearer.xsl file.

The procedures are now complete.

Create a Federated Identity Management endpoint

This object in the DataPower configuration represents the configuration on how to contact the remote Federated Identity Management server. These values allow the device to successfully connect to the Federated Identity Management server. The resulting object is used in the configuration of an AAA policy.

1. Type IBM Tivoli Federated Identity Manager into the search bar and click Add to create a new Federated Identity Management endpoint object.
2. Set the name to tfim-sts.
3. Set the Endpoint Type to OAuth STS.
4. Set the server to the IP address provided for the Federated Identity Management server (such as 192.168.100.105).
5. Set the port to 9443.
6. Set the Compatibility Mode to Version 6.2.
7. Set the Applies-To Address to https://<TFIM_IP>:9443/sps/<TFIM_Federation>/oauth20.

   Substituting the IP address provided for the TFIM server in for <TFIM_IP> and the TFIM Federation name in for <TFIM_Federation>.

8. For the SSL proxy profile, select tfim-oauth that was imported previously. This proxy profile contains a validation credential to authenticate the Federated Identity Management server. As a best practice, configure the SSL Proxy Profile to authenticate the Federated Identity Management server before sending the access token and enforcement point credentials. You can do this by adding the SSL certificate from the Federated Identity Management server to the SSL Proxy Profile's Crypto Validation Credential object.

   The Username and Password fields are used as basic authentication credentials for the appliance when connecting to the Federated Identity Management validation endpoint. This user is configured on the Federated Identity Management server with permissions to submit WS-Trust requests.

9. Set the Username to dp_tep as shown in Figure 8.
10. Set the password and password confirmation to p4$$w02d.
11. Click Apply.

    Figure 8. Federated Identity Management server configuration

Create an AAA policy

DataPower uses an AAA policy to authenticate the OAuth client making a request for the resource, and also to verify the access token presented by the client.

1. Type AAA Policy in the search bar and click Add to create a new AAA policy object.
2. Set the Name to oauth-tfim-aaa as shown in Figure 9.

   Figure 9. AAA Policy Main tab

3. In the Extract Identity Tab, check Client IP Address as shown in Figure 10.

   Figure 10. AAA Policy Extract Identity tab

4. In the Authenticate Tab, select Custom Template as the method. As the URL, select local:///bearer.xsl, as shown in Figure 11. This allows all requests to pass the authentication step successfully. This serves to allow any client with access to the bearer token (access_token in this case) to use it. You can have a use case where you would like to authenticate the client. It can be accomplished that uses the EI and AU steps as you would normally for an AAA policy.

   Figure 11. AAA Policy Authenticate tab

5. In the Extract Resource tab, check URL Sent by Client as shown in Figure 12.

   Figure 12. AAA Policy Extract Resource tab

6. In the Authorize Tab, select OAuth as the method.
7. Select Maximum for Cache authorization results, and set the Cache Lifetime to 60 seconds as shown in Figure 12. This configures the AAA policy to cache Federated Identity Management OAuth authorization results for up to 60 seconds. The effective Time To Live (TTL) is less if the Federated Identity Management server indicates that the access token expires sooner. Select TFIM Authorization endpoint as the OAuth Endpoint Type.
8. For the TFIM Endpoint, select the tfim-sts, which is the TFIM Endpoint object created in the previous step.
9. Set Enforce Scope to on.

   Figure 13. AAA Policy Authorize tab

10. Click Apply.

Create an XML Firewall

In this case, you use an XML Firewall service to accept inbound resource requests, validate the access token, and allow or disallow access to the resource requested. A Multi-Protocol Gateway can also be used.

1. Type Advanced in the navigation search and click New Advanced Firewall.
2. Enter tfim-oauth-ep in the Name field as shown in Figure 14.
3. Set the Local IP Address to 0.0.0.0 and set the Port Number to the value not in use on the device, such as 8888.
4. Select tfim-oauth-ep-cp for the Reverse (Server) Crypto Profile.
5. Set the Firewall Type to Loopback. Note that this article uses a loopback only for demonstration purposes. Normally, a backend destination is used.
6. Change the Request Type to Non-XML.
7. Change the Response Type to XML.

   Figure 14. Advanced XML Firewall configuration

Create the processing policy

Now you create the processing policy for the service.

1. Click + under Processing Policy. A new window opens.
2. Enter tfim-oauth-ep in the Name field as shown in Figure 15.
3. Click New Rule. A new processing rule line appears with the Match action highlighted.
4. Set the Rule Direction to Client to Server.
5. Double-click the Match action. A new window opens.
6. Click + to create a new Matching Rule.
7. Configure the Matching Rule as follows:
   • Name: All
   • Matching Rule: Match Type URL; URL Match *
8. Click Done or Apply as needed to return to the Processing Policy pane.
9. Drag an Advanced action onto the processing line and double-click it.
10. Select Convert Query Params to XML and click Next. Click Done.
11. Drag an AAA action onto the processing line and double-click it.
12. Select oauth-tfim-aaa as the AAA Policy. Click Done.

    Figure 15. AAA action

    The request rule resembles the illustration shown in Figure 16.

    Figure 16. Processing policy rule

13. Click New Rule. A new processing rule line appears with the Match action highlighted.
14. Set the Rule Direction to Server to Client.
15. Double-click the highlighted Match Action.
16. Select All from the dropdown list of available Matching Rules and click Done.
17. Click Apply Policy. The Policy window closes.
18. Click Apply to complete the XML Firewall configuration. Click Save Config to save your work.
19. Go into the XML Firewall service configuration and click Show Probe as shown in Figure 18. A new window opens.

    Figure 17. Show Probe

20. Click Enable Probe as shown in Figure 18.

    Figure 18. Probe transaction list

Send request

In the following example, there is a web-based OAuth client listening on port 3000 that performs the OAuth token request handshake with the Federated Identity Management server. The response is a valid access token that can be used to request the resource from the resource server, which is now protected by the DataPower device. In this case, the request URI is used as the scope.

1. First, use the following cURL command to obtain an access token from the Federated Identity Management server:

     curl -k https://oauthclient:3000/getUserInfo/uid/12345678

   This returns an <access_token> node similar to the following:

     <access_token>FIsqmCZ5yp1GFYh6iYm7</access_token>

2. Extract the token and execute the following cURL command:

     curl -k https://<DataPower_IP>:<ResourceServer_Port>/getUserInfo/  uid/12345678 -H "Authorization: Bearer <AccessToken>" –d   "my-name=<name>&my-job=<title>"

3. Substitute the DataPower IP address for <DataPower_IP>, the port you used for the XML Firewall for <ResourceServer_Port>, the access_token extracted from the last command for <AccessToken>, your name for <name>, and your job title for <title>.

   This sends the access token to the token enforcement point you created as a bearer token in the Authorization header. You should receive a response similar to the following:

     <?xml version="1.0" encoding="UTF-8"?> <request><url>/getUserInfo/uid/12345678</url><base-url>/   getUserInfo/uid/12345678</base-url><args src="url"/><args   src="body"><arg name="name">Dave</arg><arg   name="title">Engineer</arg></args></request>

1. In the Probe Transaction window, click the magnifying glass in any of the successful transactions (see Figure 19).

   Figure 19. Probe transaction detail

2. Click the AAA action icon (see Figure 20).

   Figure 20. Probe Extension Trace

3. Click (show nodeset) in the request column to look at the WS-Trust request sent to the TFIM Validation endpoint.
4. Click the (show nodeset) in the response column to look at the WS-Trust response returned from the TFIM Validation endpoint. In Figure 21, notice the stsuuser:Attribute nodes with type="urn:ibm:names:ITFIM:oauth:response:attribute".

   Figure 21. Probe Response Node display

5. Click the magnifying glass immediately after the AAA action. Select the Headers tab (see Figure 22). Notice that there are new request headers for each of the stsuuser:Attribute nodes in the WS-Trust response. These are set for consumption by the backend, and can be disabled by setting Export Response Attributes to "off" in the AAA policy. These values are also available as input to the AAA PostProcessing's custom XSLT method.

   Figure 22. Probe Headers display

Conclusion

This article showed how to use DataPower as the resource server enforcement point in an OAuth protocol exchange, as well as demonstrated a configuration example implementing this role.

The OAuth protocol specification covers many other scenarios. This series of articles on DataPower implementation of the OAuth protocol provides more details on how DataPower can act in other capacities in an OAuth exchange.

Acknowledgments

The authors would like to thank Shiu-Fun Poon for her review of this article.