Using OAuth on IBM WebSphere DataPower Appliances, Part 6: Using the authorization code grant in a DataPower OAuth configuration

Part 6 of this multi-part series covers OAuth 2.0 support in WebSphere® DataPower Appliances. This article covers the purpose of an authorization code grant type and how you can use it. It also provides instructions on how to configure DataPower to support an authorization code grant type.

Shiu Fun Poon (shiufun@us.ibm.com ), Security Architect, IBM

Photo of Shiu Fun PoonShiu Fun Poon is the Security Architect in the WebSphere DataPower Appliance development team. She has worked in many different areas and features of DataPower appliances. She currently leads DataPower's support for OAuth 2.0 functionality. Her past DataPower projects included WS-Security Policy, various WS-Security features, appliance RAS features, 7198/7199 appliance release, and third party integration with the appliance.



03 August 2012

Introduction

Authorization code is one of the grant types that supports the traditional OAuth protocol. In this article, we will provide background information about the authorization code grant type, its purpose, and how to use WebSphere DataPower to provide this OAuth grant type support in a customer environment.


Overview of an authorization code grant type

According to the specification (IETF-OAuth20), an authorization grant type is optimized for confidential clients. A confidential client is a client that maintains the confidentiality of their credentials. With an authorization code grant type, the client must be able to interact with the resource owner's user-agent and receive an incoming request with redirection. This grant type is appropriate for server side web applications.

Figure 1 provides a high level overview of the authorization code grant type.

Figure 1. Overview of Authorization Code Grant Type
Overview of Authorization Code Grant Type

This section explains the steps shown in Figure 1:

  1. Register an OAuth client application with the authorization server. This gives the OAuth client application a client_id (this may also be known as application id) and client_secret (this may also known as application secret). Most likely, this step is performed by the application developer, in conjunction with the API provider.
  2. (Optional) The resource owner authenticates with the application.
  3. The resource owner triggers an operation that requires the OAuth client application to access the resource owner's resource, which resides on the resource server.
  4. The OAuth client application redirects the resource owner to the authorization server.
  5. The resource owner authenticates with the authorization server and users grant permission for the OAuth client application to access the resource owner's resource.
  6. The resource server sends a redirect to the resource owner's agent. This redirect contains an authorization code for the OAuth client application.
  7. The authorization code is sent to the OAuth client application with the redirect from Step 6.
  8. The OAuth client application sends its credentials (from Step 1) and authorization code (from Step 7) to the authorization server.
  9. After the authorization server verifies the credentials and authorization code, it issues an access_token to the OAuth client application.
  10. The OAuth client application uses the access_token to access the resource, which resides on the resource server.
  11. The resource server, after verifying the access_token is valid, returns the resource to the OAuth client application.
  12. The OAuth client application continues the operation, which was triggered in Step 3.

Download files

Included in this article are the following sample files that you can download:

  • stylesheet.zip: This file contains the stylesheets that are used for this article.
  • client.zip: This file contains the sample OAuth client, which supports the authorization code grant type.
  • json-backend.zip: This file contains the MPGW that would act as the backend resource server (for testing purpose only).
  • export.zip: This file contains the exported configuration that contains the WTS and MGPW specified in this article.
  • key.zip: This file contains the key material used for export.zip.

Use the authorization code grant type

This grant type allows the resource owner to share the resources with a third party client without sharing his or her credential. Most importantly, the access permission (in the form of access_token) is never shared with the resource owner. This provided additional security and assurance that the access to the resource is limited to the OAuth client.

The use case provided in the specification, IETF-OAuth20, is a perfect example. In the example, it discusses how the resource owner wants to print her pictures with a printing service (OAuth Client application). However, her pictures are located at another photo sharing site (resource server). For this scenario, the resource owner never shared her credential to access her photo, username, and password with the printing service.


Where does WebSphere DataPower fit in?

Using the same scenario above, we position DataPower as the authorization server, and also as the enforcement point for the resource server.

When DataPower acts as an authorization server, it provides:

  • An authorization endpoint: This is used by the OAuth client application to obtain authorization from the authenticated resource owner.
  • The token endpoint: This is used by the OAuth client application to exchange an authorization code for an access_token.

When DataPower acts as an enforcement point for the resource server, it verifies the access_token, and DataPower only allows the request to the backend resource server if the access_token is valid.

In this article, the exported configuration for the following is provided. We also provide a PHP client that you can use to test the authorization code grant type supported by DataPower. The PHP client must be running on a web server that supports PHP.

There are three distinct operations:

  1. Register the OAuth client application with DataPower (Figure 1 - Step 1): Create an "OAuth Client Profile" and define an AAA for supporting DataPower to act as the authorization server. To authenticate the resource owner (Figure 1 - Step 5), you will extract the resource owner's identity using "HTTP Authentication Header" (Extract Identity, EI), and verify the identity using "Use DataPower AAA Info File" in the Authenticate step. You will then define an AAA for the enforcement point for the resource server.
  2. Configure DataPower to act as an authorization server (Figure 1 - Steps 5 to 9): Create a Web Token Service, using the AAA created in Step 1.
  3. Configure DataPower to act as enforcement point for the resource server (Figure 1 - Steps 10 to 11): Create a Multi-Protocol Gateway to use the AAA from Step 1.

Register the OAuth client application

As with DataPower, this amounts to creating a configuration object. In this case, you create an "OAuth Client Profile" and an AAA object, which will use the OAuth client.

Create an OAuth Client Profile and group

  1. In the Control Panel, type OAuth and select OAuth Client Profile, as shown in Figure 2.
    Figure 2. OAuth client profile
    OAuth client profile
  2. Click Add to register a new OAuth client as shown in Figure 3.
    Figure 3. Register a new OAuth client
    Register a new OAuth client
  3. Enter information for the new OAuth client and click Apply.
    • Name (client_id):myregistered_oauthclient
    • Customized OAuth: (Optional) This overrides the DataPower OAuth handling. We will cover this in detail in Part 9 of the series.
    • OAuth Role: Check the authorization and token endpoints, and the enforcement point for the resource server.
    • Supported Authorization Grant Type: Authorization code
    • Generate Client Secret: Uncheck it.
    • Client Secret (client_secret):passw0rd
    • Redirect URI: List out all the valid redirect URI that the new OAuth client supports. For this article's purpose, we will use a regular expression that will match on all the HTTPS URLs: https://{1}\S+.
    • Scope: Specify the scope that this client will support.
    • Shared Secret: The shared secret crypto object that is used to protect the token. It must be 32 bytes in size.
    • Authorization Form: This specifies the XSLT that will generate the OAuth authorization form and error page for the resource owner. A stylesheet example, store:///OAuth-Generate-HTML.xsl, is shipped with the application. The stylesheet provides an example on how this can be done.
    • Additional OAuth Process: (Optional) A stylesheet example is provided with this article on how to create an HTTP header, which contains the resource owner's identity for the backend services, add-processing.xsl. This will be covered in more detail in Part 8 of the series.
    Figure 4. OAuth client profile
    OAuth client profile
  4. Create an "OAuth Client Group" by selecting OAuth Client Group from the Control Panel, as shown in Figure 5.
    Figure 5. Create an OAuth Client Group
    Create an OAuth Client Group
  5. Enter a name for "Name". Click Add and click Apply as shown in Figure 6.
    Figure 6. Create an OAuth client group to be used for AAA
    Create an OAuth client group to be used for AAA

Create an AAA to be used by DataPower

  1. Create the AAA to be used for the authorization server. From the Control Panel in the search box, type AAA as shown in Figure 7.
    Figure 7. Select the AAA policy
    Select the AAA policy
  2. Click Add to add a new AAA policy for the authorization server as shown in Figure 8.
    Figure 8. Add a new AAA policy for the authorization server
    Add a new AAA policy for the authorization server
  3. On the "Main" tab, enter a name for the AAA policy as shown in Figure 9.
    Figure 9. Enter a name in the Main tab
    Enter a name in the Main tab
  4. On the "Extract Identity" tab (Figure 10), select HTTP Authentication Header for the resource owner's authentication. Select OAuth to indicate this is part of the OAuth protocol support. Choose the OAuth Client Group, which contains all the OAuth clients that this AAA will support.
    Figure 10. Extract Identity tab
    Extract Identity tab
  5. On the "Authenticate" tab, select Use DataPower AAA Info File as the method, and select store:///AAAInfo.xml as the AAA Info File URL. This defines "how" to authenticate the resource owner. There are multiple users defined in store:///AAAInfo.xml. For this article's purpose, we will use the identity of "fred" with a password of "flintstone".
    Figure 11. Authenticate tab
    Authenticate tab
  6. On the "Extract Resource" tab, check Processing Metadata and select oauth-scope-metadata to pick up the requested scope from the OAuth client application, as shown in Figure 12.
    Figure 12. Extract Resource tab
    Extract Resource tab
  7. Click Apply to save the AAA policy for the authorization server as shown in Figure 13.
    Figure 13. Save the AAA policy for the authorization server
    Save the AAA policy for the authorization server

Create an AAA to be used by DataPower

  1. Repeat the above process to create a second AAA object. This additional AAA will be used to enforce access to the resource server. On the main tab, enter a name for "Name".
    Figure 14. Extract Identity tab
    Extract Identity tab
  2. On the "Authenticate" tab, the given request will be verified during "Extract Identity", as shown in Figure 15. Choose Pass Identity Token to the Authorization Step.
    Figure 15. Authenticate tab
    Authenticate tab
  3. On the "Extract Resource" tab, select URL Sent by Client as shown in Figure 16. You will check the scope in access_token against those sent by the OAuth client. Select Processing Metadata, then oauth-scope-metadata to access the verified requested scope against the "OAuth Client Profile".
    Figure 16. Extract Resource tab
    Extract Resource tab
  4. (Optional) On the "Map Resource" tab (Figure 17), provide a stylesheet that will verify the two "Extract Resources" from above. Click Apply to save the AAA policy. (An example stylesheet, accesstoken-check-resource.xsl, is provided with this article.)
    Figure 17. Map Resource tab
    Map Resource tab

Register DataPower to act as an authorization server

  1. Create a Web Token Service by using the wizard. Type Web Token Service at the search box under the Control Panel. Select New Web Token Service as shown in Figure 18.
    Figure 18. Choose a new Web Token Service to launch the wizard
    Choose a new Web Token Service to launch the wizard
  2. Enter a name for the "Web Token Service Name" and click Next, as shown in Figure 19.
    Figure 19. Provide a name for the Web Token Service
    Provide a name for the Web Token Service
  3. Provide a port and the SSL proxy (see Figure 27 on how to create a SSL Reverse Proxy Profile) for the listening port, as shown in Figure 20. Click "+" and click Next.
    Figure 20. Define the port and SSL proxy profile for the authorization server
    Define the port and SSL proxy profile for the authorization server
  4. Select the AAA that you defined for the authorization server and click Next, as shown in Figure 21.
    Figure 21. Select the AAA
    Select the AAA
  5. Review the configuration and click Commit, as shown in Figure 22. Select Done in the next tab.
    Figure 22. Commit the changes
    Commit the changes

Register DataPower to act as enforcement point for the resource server

  1. Choose Multi-Protocol Gateway for the enforcement point for the resource server. Choose Multi-Protocol Gateway from the Control Panel, or click Multi-Protocol Gateway under the Services grouping, as shown in Figure 23.
    Figure 23. Choose the Multi-Protocol Gateway
    Choose the Multi-Protocol Gateway
  2. Click Add to add a new Multi-Protocol Gateway to protect the backend resource server, as shown in Figure 24.
    Figure 24. Create a new Multi-Protocol Gateway
    Create a new Multi-Protocol Gateway
  3. Enter the following (see Figure 25):
    • Multi-Protocol Gateway Name: Enter a name for the MPGW.
    • Backend URL: Enter the resource server's address.
    • Request Type: Non-XML
    • Response Type: JSON (our backend returns a JSON object)
    • Front Side Protocol: Click "+" for 'HTTPS (SSL) Front Side Handler' (see Figure 26). This enables a "GET" method, provides a name, port, and SSL Proxy profile. DataPower will act as an SSL Server, so it is the profile that supports "Reverse" as SSL Direction (see Figure 27).
    • Multi-Protocol Gateway Policy: Click "+" to create a new policy.
    Figure 25. Create a Multi-Protocol Gateway
    Create a Multi-Protocol Gateway
    Figure 26. Create the HTTPS front side protocol handler
    Create the HTTPS front side protocol handler
    Figure 27. Create an SSL Reverse Proxy
    Create an SSL Reverse Proxy
  4. Create the Multi-Protocol Gateway Policy (see Figure 28). Enter a policy name and click Add Policy.
  5. Create the three rules as follows:
    • First rule: (This deals with favicon.ico request from the browser.)
      • Direction: Client to server. This is the request rule.
      • Action: Match
        • Matching Type: URL
        • URL Match: /favicon.ico
      • Action: In Advanced, Set Variable.
        • Variable Name: var://service/mpgw/skip-backside
        • Variable Assignment: 1
      • Action: Result
    • Second rule: (This verifies the access_token for the resource access.)
      • Direction: Client to server. This is the request rule.
      • Action: Match
        • Matching Type: URL
        • URL Match: /*
      • Action: Advanced > Convert Query Params > XML (choose the default for this action).
      • Action: Select the AAA that was created earlier for the enforcement point for the resource server.
      • Action: Result
        • Method: Get
    • Third rule:
      • Direction: Server to Client. This is the response rule.
      • Action: Match
        • Matching Type : URL
        • URL Match : /*
      • Action: Result
  6. Select Apply Policy, then select Apply on "Configure Multi-Protocol" as shown in Figure 28. In the Gateway, select Save Config.
    Figure 28. Create a Multi-Protocol Gate style policy
    Create a Multi-Protocol Gate style policy

Miscellaneous

For testing purposes, you will create a MPGW that returns a JSON object. This is used to simulate a backend that will utilize the resource owner's identity. This MPGW is provided in the exported configuration, which is included with this article.


Testing the registered OAuth client

A PHP client is provided with the article. The client will simulate an OAuth client that supports the authorization code.

  1. Access code.htm on the web server, http://<webserver>/code.htm (see Figure 29):
    • Endpoint: This is the authorization endpoint hosted by WTS from above.
    • redirect_uri: This is the PHP client that is included in this article. It is stored on the webserver.
    Figure 29. Specify the authorization endpoint and other information
    Specify the authorization endpoint and other information
  2. The authorization server, which is a WTS listening at 7070, is prompted for the resource owner's authentication. We used fred/smith as the resource owner as shown in Figure 30.
    Figure 30. Enter the identity of the resource owner
    Enter the identity of the resource owner
  3. The authorization server is prompted for Fred's permission to share his resource, as shown in Figure 31.
    Figure 31. Approval form
    Approval form
  4. Note that the authorization code that was generated (code), and now entered as the client_secret for the OAuth client, myregistered_oauthclient (Figure 32). This is for the OAuth client to request an access_token, based on the authorization code it received earlier.
    Figure 32. Requesting for an access_token
    Requesting for an access_token
  5. An access token was issued to the OAuth client, myregistered_oauthclient, entered as the resource server enforcement point. This is the MPGW that was created earlier in the article. resource_endpoint is the MPGW that acts as the enforcement point for the resource server (Figure 33).
    Figure 33. Retrieve the resource protected by MPGW
    Retrieve the resource protected by MPGW
  6. The actual response is from the resource MPGW created from the Miscellaneous step. Note the name as this is the resource owner's identity and access_token in Figure 34. The "name" matches the identity of the resource owner that the resource belongs to, and the "access_token" matches from the request. The resource owner's identity is extracted from access_token.
    Figure 34. The result from the backend service
    The result from the backend service

Conclusion

In this article, you learned the purpose of an authorization code grant type. This grant type is appropriate for server-side web application to maintain the confidentiality of its credentials. This grant type also provides additional security benefits, including the ability to authenticate the OAuth client, in which the access_token is sent to the OAuth client, without exposing it to the resource owner.

For additional information, see the rest of the article series as follows:

The following articles in the series will be available in the weeks to come:

  • Part 8: Customizing the Websphere DataPower native support for OAuth scope, identity processing, and additional processing
  • Part 9: Customizing the DataPower native support for OAuth authorization codes and access tokens
  • Part 10: Troubleshooting DataPower OAuth protocol support

Acknowledgements

The author would like to thank John Rasmussen and Peter Argue for their review of this article.


Downloads

DescriptionNameSize
Stylesheets filestylesheet.zip3KB
Sample OAuth client fileclient.zip3KB
MPGW for testing purposesjson-backend.zip479KB
Exported configuration fileexport.zip489KB
Key material for export.zip filekey.zip4KB

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=829237
ArticleTitle=Using OAuth on IBM WebSphere DataPower Appliances, Part 6: Using the authorization code grant in a DataPower OAuth configuration
publish-date=08032012