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

Part 4 of this multi-part series describes WebSphere® DataPower Appliance support for the OAuth 2.0 resource owner password credential grant type. It covers configuration for both the authorization server and the resource server.

Paul Glezen (pglezen@us.ibm.com), Consulting IT Specialist, IBM

Photo of Paul GlezenPaul Glezen is an IT Specialist with IBM Software Services for WebSphere (ISSW). He started application server consulting in 1998 with the IBM CORBA-based C++/Java product known as Component Broker. His current product focuses are DataPower and WebSphere Application Server development and security configurations.



Teri Wen (teriwen@tw.ibm.com), Software Engineer, IBM

Photo of Teri Wen Teri Wen is a Software Engineer at the IBM Taiwan – China Software Development Lab (CDL), where she works on WebSphere DataPower Appliances Quality Assurance. She is currently a Test Engineer for DataPower's OAuth 2.0 support, and has worked on the quality assurance of many security features in the past releases.



June 2014 (First published 03 August 2012)

Also available in Portuguese

Introduction

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.

Note from the authors

We are in the process of substantially revising the entire series of the DataPower OAuth articles, including Parts 8 to 10. We expect to complete the full series update by year end. Meanwhile, we will release each part as it becomes available.

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

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 OAuthArticleKeys.zip 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 AccountLoopback.zip 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 Part4BeginState.zip 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 shows an empty Client Secret field. The field is not visible until you uncheck the Generate Client Secret box. Once you populate the Client Secret field, the Generate Client Secret box disappears. To get it back again, remove the Client Secret value. This is the state shown in Figure 2.

Figure 2. 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

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

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

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
  <Authenticate>
    <Username>fred</Username>
    <Password>smith</Password>
   <OutputCredential>admin</OutputCredential>
 </Authenticate>

 <Authorize>
   <InputCredential>admin</InputCredential>
    <InputResource>getAccount</InputResource>
    <Access>allow</Access>
  </Authorize>

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
  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

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 http://127.0.0.1:5001. 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

Testing

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 https://192.168.1.105:5040/ --user password-client:passw0rd -d 
"grant_type=password&username=fred&password=smith&scope=/getAccount"

{ "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 https://192.168.1.105:5041/getAccount -H "Authorization:Bearer AAEPcG...6GkYzfZhaM"

HTTP/1.1 200 OK
{
  "name": "myAccount",
  "balance":1.00,
}

Conclusion

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.


Downloads

DescriptionNameSize
Code sampleOAuthArticleKeys.zip3KB
Code samplePart4BeginState.zip520KB
Code sampleAccountLoopback.zip524KB

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=829233
ArticleTitle=Implementing OAuth on IBM WebSphere DataPower Appliances, Part 4: Grant type scenario for resource owner password credentials
publish-date=06032014