Implementing OAuth on IBM WebSphere DataPower Appliances, Part 4

Grant type scenario for resource owner password credentials


Content series:

This content is part # of # in the series: Implementing OAuth on IBM WebSphere DataPower Appliances, Part 4

Stay tuned for additional content in this series.

This content is part of the series:Implementing OAuth on IBM WebSphere DataPower Appliances, Part 4

Stay tuned for additional content in this series.

The OAuth authorization protocol provides for limited sharing of user resources without sharing user credentials. An access token replaces username and password for access to the resource. Section 4 of the IETF OAuth 2.0 Specification Framed describes four grant type scenarios. One of these is the resource owner password credential grant type. It is a two-legged scenario that involves exchanging the resource owner's username and password for an access token and using that token to access resources. For more information about two-legged and three-legged processes, see Part 1 of the series, Introducing OAuth 2.0 support in DataPower, or see IETF OAuth 2.0 Authorization Framework.

The crucial way in which this scenario differs from the three-legged scenarios described in Part 1 of this series is that the client knows the resource owner's credentials. The first sentence of the previous paragraph stated that OAuth allows clients to be granted access to resources without the resource owner's credentials. The scenario in this Part 4 is a specialized case where the client is a highly privileged application that actually possesses the resource owner's credentials. Since the resource server only permits access via an access token, the client must still exchange the resource owner credentials for an access token. And in the case of a confidential client, it must also provide its client ID and secret in addition to the resource owner's credentials.

As shown in Figure 1, a privileged application on your device needs to access your resources, such as pictures and profile information stored on a social media network. It sends a token request containing the resource owner username and password as well as client information to an authorization server and receives an access token. It uses the access token to access your private resources on your behalf. DataPower can perform two important roles in this scenario: as an authorization server and/or as a policy enforcement point for a resource server. Acting as an authorization server, DataPower accepts and verifies an OAuth request and generates an access token. DataPower acting as an enforcement point for a resource server verifies the access token and validates it against the resource the client is requesting. DataPower provides enhanced access control of resources with the OAuth authorization protocol.

Figure 1. Resource owner password credential grant type flow
Resource owner password                     credential grant type flow
Resource owner password credential grant type flow

This article will step through the configuration of the OAuth resource owner password credential grant type on DataPower and the generation of an access token. The high level steps are:

  1. Create an OAuth client object.
  2. Create an OAuth client group object.
  3. Create AAA policies for authentication and authorization.
  4. Create an authorization server using the Web Token Service to implement Step 1 of Figure 1.
  5. Create a resource server enforcement point using the Multi-Protocol Gateway to implement Step 2 of Figure 1.

An OAuth client profile is a DataPower object containing detailed information about a client application. The profile defines the grant type and the role it supports, among other information. An OAuth client group object combines multiple OAuth clients in a managed group. Once the OAuth client and group are created, AAA policies for authentication and authorization are defined for both the client application and the resource owner. Next, the web token service is configured in order to generate tokens based on an OAuth AAA policy. Lastly, a Multi-Protocol Gateway (MPGW) is configured as an enforcement point for the resource server. It verifies tokens and allows or denies access to resources.

Preparing for the DataPower configuration

  1. Create a new DataPower application domain for this article and switch to it.
  2. Set the default log level of the domain to information.
  3. This article uses the same set of shared secret and SSL keys used by the other articles in this series. From the Download section of this article, download and unzip it if you haven't already. Upload sharedSecretKey.txt, sslserver-privkey.pem, and sslserver-sscert.pem into the cert: directory of your new application domain.
  4. This article uses a simple XML Firewall for the backend. This is packaged in an archive named from the Download section. Download and import this file if you haven't already. If this XML Firewall is already running in another application domain from a previous exercise, then you may skip this step and reuse the existing one.
  5. Download and import provided with this article. It contains the following:
    1. An SSL Proxy Profile sslserver that references the SSL key files from Step 3.
    2. A processing policy used by the resource server's enforcement point MPGW, mpgw-oauth-rs.
    3. A local file, local:///AAAInfo.xml, used for simple authentication and authorization.
  6. Verify the following:
    1. The SSL Proxy Profile sslserver state is up.
    2. The XML Firewall loopBack state is up. (This may be deployed to a different application domain if you deployed it earlier.)
    3. The file local:///AAAInfo.xml exists.
    4. Navigate to Services > Multi-Protocol Gateway > Multi-Protocol Gateway Policy and check that the mpgw-oauth-rs state is up.

The OAuth client profile object

An OAuth client profile object provides DataPower with the information about an OAuth client needed to authenticate it and issue access tokens particular to the client. In this exercise, the OAuth client profile objects has already been imported since it is also a dependency of the MPGW policy imported above. Navigate to Objects > Crypto Configuration > OAuth Client Profile and select the password-client entry. It should resemble Figure 2. Below is a list of items configured on this object when it was created.

  • Name: password-client
  • Supported Authorization Grant Type: Resource Owner Password Credential
  • Client-Type: Confidential
  • Authentication Method: Secret
  • Uncheck Generate Client Secret to expose Client Secret (see the sidebar about Figure 2).
  • Client Secret: passw0rd
  • Scope: getAccount|getBalance
Figure 2. OAuth Client Profile configuration
OAuth Client Profile configuration
OAuth Client Profile configuration

The shared secret key

A shared secret key object is required to support the encryption of the authentication credentials. The sharedSecretKey.txt file that you uploaded contains a 32-byte key (256-bit). You can use either one of two formats for this key file:

  • 32 ASCII characters
  • 64 hex digits

The second option is preferred for security. To indicate you are using the hex method, the first two characters should be "0x" (a zero followed by lowercase "x"). For more information about creating randomized strings of 64 hex digits, see Perfect Passwords.

A shared secret key object was created as part of the import. You would create a new one by uploading the text file, navigating to Objects > Crypto Configuration > Crypto Shared Secret Key, and clicking the Add button.

Figure 3. Crypto shared secret configuration
Crypto shared secret                     configuration
Crypto shared secret configuration

The shared secret key is used by DataPower to sign and encrypt the access token. In this case, it's not being "shared" with any non-DataPower entities. It's a "shared key" in the sense that it's a symmetric encryption key as opposed to asymmetric. You are encouraged to experiment with generating your own shared secret key to use with this exercise.

The OAuth client group

OAuth client profiles are organized into OAuth client groups. A client group represents all the clients that are registered with an authorization service. The import for this article created such a group called client-group. Navigate to Objects > Crypto Configuration > OAuth Client Group and select client-group.

The OAuth client group was created with the following steps. The completed configuration is shown in Figure 4.

  1. Search for OAuth Client Group in the WebUI search box.
  2. Click OAuth Client Group.
  3. Click Add.
  4. Enter a client group name.
  5. Select and add the OAuth clients.
  6. Click Apply.
Figure 4. Configure the OAuth client group
Configure the OAuth client group
Configure the OAuth client group

The Authorization server AAA policy

An AAA policy will be used by the OAuth authorization server. DataPower, acting as an authorization server, will respond to authorization requests from an OAuth client application. DataPower issues an access token if the request is approved. An access token is specific to an OAuth client application and is limited to a specific scope (or resource). Before creating the AAA policy, let's first discuss how we're going to authenticate and authorize client requests.

Most configurations will use directory products such as Tivoli® Access Manager or another LDAP provider for authentication and authorization. In this sample, we'll simply use the DataPower AAA Info file. A sample comes packaged as store:///AAAInfo.xml. You imported a customized one into local:///AAAInfo.xml as shown in Figure 5. Entries within the AAA Info file can be used to authenticate your OAuth client credentials and authorize client requests for specific resources, called scopes in OAuth terminology.

Figure 5. AAAInfo.xml in the local:// directory
AAAInfo.xml in the local:// directory
AAAInfo.xml in the local:// directory

Within the file are authentication entries for resource owner (fred) with the associated password (smith). Listing 1 shows these entries.

Listing 1. Sample access token request and response


The <Authenticate> section determines the entity that is allowed to make grant decisions. The <Authorize> section determines on which scope (<InputResource>) the entity is allowed to grant. The value of <InputResource> must match the requested scope on a grant request. We will revisit this concept when validating the sample (see Listing 2 near the end of this article).

Creating an AAA Policy for authentication

  1. Search for "AAA Policy" in the WebGUI search box.
  2. Click AAA Policy.
  3. Click Add.
  4. Enter the AAA policy name as AuthServerAAA.
  5. Select the Identity extraction tab as shown in Figure 6.
    1. Check the HTTP Authentication header box.
    2. Check the OAuth box. This causes the Registered OAuth clients field to appear.
    3. Select client-group as the set of registered OAuth clients.
    Figure 6. Define the Extract Identity step
    Define the Extract Identity step
    Define the Extract Identity step
  6. Select the Authentication tab.
  7. For Method, choose Use AAA information file.
  8. Select the imported local:///AAAInfo.xml file that was uploaded during the import.
  9. Select the Resource extraction tab.
  10. Check the Processing Metadata box and select oauth-scope-metadata from the dropdown.
  11. Choose oauth-scope-metadata, which will identify the scope for the client request.
  12. Select the Authorization tab.
  13. For Method, select AAA information file to authorize the request according to the AAA info file. This is to verify whether the resource owner is authorized to the requested resource (scope).
  14. Select local:///AAAInfo.xml.
  15. Click Apply.

The Web Token Service as an authorization server

We have an AAA policy (that we just created) and an SSL Proxy Profile (that we imported). This is all we need to configure the Web Token Service with the wizard. This service will receive the resource owner password credential grant request and respond with an access token for the specific scope.

The steps are just like those in Part 3 under the section called Create the Web Token Service using the AAA policy. Here, you simply list the entry fields to populate.

  1. Search for New Web Token Service in the WebUI search box.
  2. For Web Token Service Name, enter AccountWTS and click Next.
  3. For Port, enter 5040.
  4. For SSL Proxy Profile, enter sslserver that was imported.
  5. Click Add to add the source address record and then click Next.
  6. For AAA Policy, select AuthServerAAA that we created in the previous section, and click Next.
  7. Click the Commit button.
  8. Click the View Web Token Service button to view the results.
  9. Click the "..." button next to Processing Policy to view the processing rules.

    The result is shown in Figure 7.

    Figure 7. View the processing policy
    View the processing policy
    View the processing policy

Contrast Figure 7 in this article with Figure 13 of Part 3 after running the WTS wizard. Part 3 employed form-based logins for the AAA policy. Here in Part 4, we employed basic-auth for the Identity Extraction method of the AAA policy. The WTS wizard knows when it must create extra rules to serve the forms.

The Enforcement Point Service for the resource server

At the beginning of this exercise, we imported a simple resource service implemented as an XML firewall named loopBack that simply returns a hard-coded JSON file. In this section, we will configure an enforcement point service that only allows access to loopBack if the request contains a valid access token. We'll use a Multi-Protocol Gateway for this purpose.

As we learned in Part 3, there is no special wizard for creating an enforcement point MPGW from an AAA policy. Since Part 3 already demonstrated all the details of creating such an MPGW (in the more complex case of form-based login policies), we've provided the processing policy in the import. We'll identify some of the key actions it contains.

Set up the resource server using the Multi-Protocol Gateway:

  1. In the Control Panel, select the Multi-Protocol Gateway icon.
  2. To create a new Multi-Protocol Gateway, click Add.
  3. Enter the Multi-Protocol Gateway Name as oauth-mpgw-rs.
  4. For the Default Backend URL, enter This is the loopBack backend.
  5. For Multi-Protocol Gateway Policy, select the mpgw-oauth-rs policy that was imported.
  6. Select Non-XML for Request and Pass-through for Response Type.
  7. Create a Front Side Protocol Handler:
    • Click "+" to create a new HTTPS (SSL) Front Side Handler.
    • Enter the HTTPS Front Side Handler name as https_5041.
    • Enter an available port number as 5041.
    • Select the GET method check box.
    • Select an SSL proxy of sslserver.
    • Click Apply for the handler.
  8. Click Apply for the MPGW.

Figure 8 shows the selection of the pre-existing Multi-Protocol Gateway Policy (mpgw-oauth-rs). You see the single rule, which contains:

  • A Match action to match all URLs.
  • A Convert action to convert the incoming query parameters to an XML structure for consumption by the AAA policy.
  • The AAA policy with the following settings:
    • Identity extraction: Basic Authentication, OAuth, and OAuth client group client-group.
    • Authentication: Pass the Identity Token to the Authorize Step.
    • Resource extraction: Select Processing metadata and choose oauth-scope-metadata. Select URL sent by client. DataPower will compare the output from "URL sent by client" against the scope in the access token.
    • Authorization: Allow any authenticated client.
      Figure 8. Define a processing policy
      Define a processing policy
      Define a processing policy


You have completed the configuration of the authorization server and the resource server on the DataPower appliance. You have two avenues available to you for testing:

  • The curl command line tool to simulate both the resource owner and the client application. You can download the curl tool.
  • A Node.js application to simulate the client while you and your browser simulate the resource owner. You can download the Node.js application.

The rest of this section explains how to use the curl tool. The Node.js application provides instructions on its homepage.

Listing 2 shows a sample request using curl to invoke the authorization server with the required parameters. Note that the scope parameter is consistent with the authorization in the AAAInfo.xml file from Listing 1. If you adjust the scope to /getMyAccount, it will fail with insufficient_scope. It is important to include the leading slash in the scope parameter. That's because the AAA policy associated with the enforcement point has URL sent by client set in the Resource extraction phase. The URL always starts with a slash. If the scope doesn't, then they will never match and authorization will always be denied. Listing 2 also shows a response containing the (clipped) access token.

Listing 2. Sample access token request and response
curl –k --user password-client:passw0rd -d 

{ "token_type":"bearer", "access_token":"AAEP…Aofbb3c", "expires_in":3600, 
"scope":"/getAccount" }

You can now use the access token to authenticate to the resource server. Our sample resource service is the simple loopback XML firewall. You can now use the MPGW to validate the access token. You must URL-encode the access token returned by the curl command before you send it back in an HTTP header. Check the resources for online decoders.

Listing 3 shows the access token being sent to the resource service and the associated authorization and JSON document returned by the loopBack XML firewall.

Listing 3. Access token verified by the MPGW Resource service
curl -k -H "Authorization:Bearer AAEPcG...6GkYzfZhaM"

HTTP/1.1 200 OK
  "name": "myAccount",


This article showed how to configure DataPower for the OAuth 2.0 resource owner password credential grant type. It demonstrated how to create an OAuth client with the grant type enabled, the Web Token Service as an authorization server, and the Multi-Protocol Gateway as an enforcement point. Lastly, the sample request and response of the resource owner password credential grant type helped to provide guidance when generating and sending requests to the DataPower appliance.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Implementing OAuth on IBM WebSphere DataPower Appliances, Part 4: Grant type scenario for resource owner password credentials