Using OAuth: Enabling the OAuth service provider in WebSphere Application Server

OAuth 2.0 service provider support was added as part of IBM® WebSphere® Application Server versions 7.0.0.25, 8.0.0.5, and 8.5.0.1. This article provides an overview of OAuth support highlighting architecture, new features, and the minimal configuration steps needed to enable the capability. The article also includes debugging tips, resource links, and pointers for advanced configurations. This content is part of the IBM WebSphere Developer Technical Journal.

Share:

Jeff Hoy (jeffhoy@us.ibm.com), Senior Security Architect, IBM China

Jeff Hoy is a Senior Security Architect in the IBM Security Solutions CTO office. He has over ten years experience with IBM, with background in portals, collaboration, next generation technology and cross-product security enablement. Jeff resides in rural North Carolina with his wife and daughter, and enjoys paragliding every chance he can get.



Bill O'Donnell, Senior Technical Staff Member, IBM

Author photoBill O'Donnell is a Senior Technical Staff Member and the Chief WebSphere Foundation Security Architect working in the WebSphere product development organization. He is responsible for the security architecture for WebSphere products. Bill has has over 25 years experience in large scale mainframe and distributed systems with a unique focus on development architecture and infrastructure architecture. Bill specializes in end-to-end infrastructure and application security. He has published a number of Redbooks and is the author of the "Secrets of SOA." Bill is a co-sponsor of the WebSphere Application Server security web site.



Shane B. Weeden, Senior Security Architect, IBM

Shane WeedenShane Weeden is a senior software engineer and product architect on the IBM Security Solutions team. He has worked in IT security since 1992, and since 2000 has been working with IBM Security products including IBM Security Access Manager and Federated Identity Manager. Shane now divides his time between customer-focused engagements and core product development activities. He holds a Bachelor of Information Technology from the University of Queensland in Australia.


developerWorks Professional author
        level

Chunlong Liang (liangch@us.ibm.com), Web Service Security Development Lead, IBM

Chunlong Liang is an architect and lead developer of web services security on the WebSphere platform. Chunlong has been in WebSphere development since 2000, and has developed many security features for the WebSphere platform. Prior to joining WebSphere team, Chunlong worked as actuarial analyst and programmer, statistician, and college mathematical teacher for many years.



08 May 2013

Also available in Chinese

Introduction

OAuth has become the de facto standard for delegated authorization across web applications. In addition to delegated access, OAuth is increasingly being used in traditional authentication and authorization roles, specifically driven by the pervasive trends of cloud and mobile. With the OAuth 2.0 specification finalized in 2012, companies have been quick to adopt the new protocol.

To support the specification, support for OAuth 2.0 service provider capability was added in IBM WebSphere Application Server versions 7.0.0.25, 8.0.0.5, and 8.5.0.1. The OAuth feature must be enabled and configured in order to leverage this capability.

This article covers the key steps required to configure WebSphere Application Server as an OAuth service provider.

Prerequisites

This article assumes a basic understanding of the OAuth 2.0 protocol; for example, understanding the difference between an OAuth client and OAuth service provider. While this is not strictly needed to follow along with the configuration steps, general understanding of the protocol is important to evaluate the security impact of OAuth in your enterprise. See Resources for good overview material.

A basic understanding of WebSphere Application Server is also assumed, specifically with regard to installing WebSphere Application Server, creating a profile, and starting and stopping servers.

To use and configure OAuth 2.0 support within WebSphere Application Server, you must have:

  • WebSphere Application Server V7.0.0.25 or V8.0.0.5 or V8.5.0.1 or later
  • Full profile.

High-level architecture and features

Let's begin with a brief overview of the OAuth implementation in WebSphere Application Server to help you understand how the configuration steps affect WebSphere Application Server. This will also be helpful in debugging and tuning the configuration settings.

WebSphere Application Server provides OAuth service provider support as a new run time service. If any OAuth providers are configured in the system, the OAuth service will initialize upon server startup.

As shown in Figure 1, OAuth components in WebSphere Application Server include:

  • OAuth runtime: Controller for the OAuth data and endpoints.
  • Configuration XML: Defines the OAuth configuration.
  • Clients database or file store: Used to register new clients.
  • Token store (database or file).
  • Authorization and Consent servlet: Handles the OAuth endpoints at http://servername /oauth2/endpoint/<provider_name>/authorize used for human browser interactions.
  • Token Request servlet: Handles the OAuth endpoints at http://servername /oauth2/endpoint/<provider_name>/token used for client programmatic interactions.
  • OAuth MBean: Programmatic configuration services.
Figure 1. OAuth components in WebSphere Application Server
OAuth components in WebSphere Application Server

OAuth-related features available in WebSphere Application Server include:

  • Full OAuth 2.0 specification compliance, including support for all core grant types: authorization code, implicit grant, resource owner password credentials, and client credentials.
  • Bearer token spec compliance.
  • Support for both public and confidential clients.
  • Support for refresh tokens.
  • Multi-tenancy support for multiple OAuth providers, differentiated by endpoints and data segregation.
  • Full cluster support.
  • In-memory dynamic caching of tokens and clients.
  • XML file or database storage of tokens and clients.
  • Configuration through direct XML editing, wsadmin commands, or run time MBeans.
  • Customizable servlet UI.
  • Sample configuration files.
  • Token revocation by administrators or users.
  • Sample administration pages and APIs.
  • Reconfiguration without the need for server restart.
  • Configurable Trust Association Interceptor (TAI) for authentication, including per-provider protected URLs and token handling.
  • Advanced rules syntax for defining TAI configuration parameters.

While WebSphere Application Server provides all OAuth capabilities needed to protect hosted applications, it does not cover the full spectrum of possible OAuth configurations. For highly advanced deployments, such as hosting OAuth as an SSO solution for non- WebSphere Application Server products, or using OAuth with highly customized data repositories, take a look at the capabilities of the IBM Tivoli® Federated Identity Manager products.

The following sections cover only the minimal setup steps needed for a basic configuration, where a basic configuration is a standalone server with a single OAuth provider using file-based persistence. For advanced setup information, see the OAuth topic in the WebSphere Application Server Information Center.


Enabling the OAuth provider

Step 1: Initial setup

  1. Ensure that your version of WebSphere Application Server matches one of the minimum levels listed above.
  2. The "snoop" servlet in the WebSphere Application Server DefaultApplication is used here for OAuth verification. The DefaultApplication is installed automatically with WebSphere Application Server, but often removed in production environments. It is an optional component for the purposes of OAuth configuration, but recommended to help validate OAuth network activity.
  3. Validate that application security has been enabled in your application server. This is not enabled by default in WebSphere Application Server.
  4. In the WebSphere Application Server administration console, navigate to Security > Global security (Figure 2). The default URL for the administration console is https://<server_name>:9043/admin.
  5. Select Enable application security, save your changes, and restart the server. If this step is skipped, OAuth token generation will still be enabled in WebSphere Application Server, but requests with OAuth tokens will not be processed by the server.
Figure 2. Enable application security
Enable application security

Step 2: Define an OAuth provider

  1. In the app_server_root/properties folder, make a copy of the OAuthConfigSample.xml file, rename it, and store it the same folder. The filename you select will become the name of your OAuth provider. For example, the provider name in this example is "DemoProvider" with a configuration file named "DemoProvider.xml." (Be aware that OAuth provider names are case-sensitive.)
  2. Open the provider XML file and take a few minutes to familiarize yourself with its contents (Figure 3). The XML file contains a series of OAuth parameters stored in XML as name:value pairs. These parameters use reasonable default values and (for the most part) do not need to be changed to create an OAuth provider.
    Figure 3. OAuth configuration settings
    OAuth configuration settings
  3. To enable a basic configuration that is easy to validate, make these updates to the configuration file (Figure 4):
    1. Lines 79 through 83: Remove the "implicit" and "client_credentials" values. The oauth20.grant.types.allowed parameter controls the OAuth grant types available, and as a security best practice, OAuth providers should only enable the grant types that will be used. Here, authorization_code is enabled as the common three-legged OAuth flow, and the password flow is enabled for ease of testing the default configuration. All configuration values can also be changed after initial setup.
    2. Lines 105 through 110: Uncomment the filter and oauthOnly parameters. These parameters instruct the OAuth provider to protect URLs that contain the string "snoop" and to enable other authentication methods for the protected URLs. These settings can also be specified in the OAuth Trust Association Interceptor configuration parameters, but it is easier to enable the settings in the OAuth configuration file to get up and running quickly.
    3. Line 122: Uncomment the oauth20.mediator.classnames parameter and its value. This parameter enables validation of users against the configured user registry in the Resource Owner Password Credentials flow.
    Figure 4. Updated OAuth configuration parameters
    Updated OAuth configuration parameters
  4. Save the file. The configuration now represents a simple OAuth service provider that protects the /snoop servlet.

Step 3: Enable the OAuth provider

Two groups of actions are needed to enable the OAuth provider based on the newly created configuration file. First, OAuth capability needs to be enabled system-wide. Once OAuth has been enabled in WebSphere Application Server, the subsequent steps register the new OAuth configuration.

To enable OAuth services:

  1. Stop the server.
  2. Navigate to the app_server_root/bin directory.
  3. Run the command in Listing 1.
    Listing 1. Run wsadmin
    wsadmin -conntype NONE -f
    installOAuth2Service.py install <nodeName> <serverName>
    -profileName <profileName>

    In this command:
    • nodeName is the node name of the target application server.
    • serverName is the server name of the target application server.
    • profileName is the name of the profile where the OAuth service provider is installed.
    • clusterName is the name of the cluster where the OAuth service provider is installed.

Upon completion, the command should give this message: ADMA5013I: Application WASOauth20SP installed successfully.

To enable the OAuth Trust Association Interceptor:

  1. Stop the server if not stopped already.
  2. Start the wsadmin command-line utility from the app_server_root/bin directory by entering the command:
    wsadmin -lang jython -conntype NONE
  3. At the wsadmin prompt, enter the command:
    AdminTask.enableOAuthTAI()
  4. Save the configuration with:
    AdminConfig.save()
  5. Exit the wsadmin command utility with: quit.

These commands will print no meaningful output when run successfully.

The OAuth capability is now enabled in WebSphere Application Server.

Next, find the cell configuration folder at <was_profile_root>/config/cells/<cell_name>. An oauth20 subfolder is used at this location to store the OAuth configuration. If the folder does not exist in your deployment, create it:
<was_profile_root>/config/cells/<cell_name>/oauth20 .

Finally, copy two configuration files from the app_server_root/properties folder into the <was_profile_root>/config/cells/<cell_name>/oauth20 folder:

  • OAuthProvider.xml, using the filename that you selected. Copying this file into the oauth20 folder will cause WebSphere Application Server to generate an OAuth provider during server startup.
  • base.clients.xml. This file will be used to store the OAuth clients on the file system.

The newly created OAuth provider is now ready for use. It will load upon server startup. However, to effectively use the provider, you need to first add an OAuth client.

Step 4: Add an OAuth client

You can use the base.clients.xml file to manually define OAuth clients. Open the new copy of that file in the oauth20 folder, and see the syntax to define OAuth clients. Take a minute to become familiar with the syntax, and then add a new client based on your desired settings (Figure 5).

Figure 5. Adding a client
Adding a client

Remember that for basic security reasons, client passwords should not be stored in cleartext. In an actual test environment, they would be encrypted and stored using the WebSphere Application Server pluggable encryption capability. In production environments, a secure database is also a good alternative to storing the client credentials on the file system. To configure database persistence for OAuth clients and tokens, see SQL statements for persistent OAuth service in the WebSphere Application Server Information Center.

The id, secret, and displayname fields contain values that you select based on your desired client attributes. The "component" must match the OAuth provider name used in Step 2 (and is case-sensitive). The "redirect" is the client redirection endpoint as specified by the OAuth protocol. The redirect is a mandatory portion of the client attributes for the authorization grant and implicit grant flows, used as a security measure, and is based on the configuration of your OAuth client. (Because the client credentials flow is used for validation in this article, the redirect value is not required to accurately reflect the client URL.)

Now that the client has been added, start the server. You can now begin using the OAuth service provider.

Step 5: Validate OAuth functionality

The typical three-legged authorization grant OAuth flow involves three players:

  • OAuth service provider, which you just configured.
  • End user (you).
  • OAuth client that usually lives in a separate security domain.

Since this article focuses on only the WebSphere Application Server portion of configuring OAuth, the steps to configure and use an OAuth client are not covered here. However you might already have an OAuth client available for testing in your environment, and if so, now is the time to break it out and put it to use.

To test the authorization grant flow, several configuration parameters will be needed by your client:

  • Client ID: OAuth client ID specified in the base.clients.xml file; in this example SuperOAuthArticle.
  • Client Secret: OAuth client secret specified in the base.clients.xml file; in this example, YourFeedbackIsAppreciated.
  • Authorization Endpoint: In WebSphere Application Server, the authorization endpoint is always http://servername/oauth2/endpoint/<provider_name>/authorize. The provider name is configurable, and so the authorization endpoint in this example is https://example.com:9443/oauth2/DemoProvider/authorize.
  • Token Endpoint: http://servername/oauth2/endpoint/<provider_name>/token; in this example, https://example.com:9443/oauth2/DemoProvider/token.

For quick setup and quick validation, the two-legged Resource Owner Password Credentials flow is enabled when defining the OAuth provider. In this flow, both the client credentials and resource owner credentials are passed directly to the server, which effectively removes the OAuth client from the protocol. This is perfect for quick testing of this nature.

An HTTP POST is mandatory when using the token endpoint to request an OAuth token. Use the cURL command-line tool to easily run an HTTP POST command and get the access token back from the server. (cURL is usually available already on most Linux® and UNIX®-based systems. If using WebSphere Application Server on Windows®, you can download cURL directly.)

Using cURL, run the HTTP POST to the token endpoint, using the password credentials flow and substituting parameters with your client ID, secret, user ID, and password. The userID and password should be the credentials of a user in the WebSphere Application Server repository. An example command and output are shown n Listings 2 and 3, respectively.

Listing 2. Example command
curl -k -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=password&client_id=SuperOAuthArticle
&client_secret=YourFeedbackIsAppreciated&username=admin&password=admin"
https://example.com:9443/oauth2/endpoint/DemoProvider/token
Listing 3. Example output
{"access_token":"ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua","token_type":"bearer",
"expires_in":3599,"scope":"","refresh_token":
"wX6LoFw6Il6RKpN4AzDbZxNK5Tzt6Chhkpiy9ocYjfcmQodMFn"}

If the response is anything else, such as a 403 or 401 HTTP error, check the OAuth specification for the meaning of the error result. The WebSphere Application Server system logs could also contain an error explanation.

Unlike token requests, when accessing a protected endpoint with the access token, the access token can be provided in several ways: as a header value, as an HTTP POST parameter, or as a URL parameter. URL parameters are easy to test in a browser, so this example will validate OAuth functionality by providing the OAuth token on the URL.

First, use a web browser to try to access the snoop servlet installed on the server, at https://<server_name>:9443/snoop:

  • If the snoop servlet loads and displays HTTP request information, you might have forgotten to enable application security in the WebSphere Application Server administrative console. The snoop servlet should not allow unauthorized access.
  • Or, you might have already logged into WebSphere Application Server in your browser session. If so, log out of the administrative console, clear your session cookies, or try another browser that has not already authenticated with WebSphere Application Server.

The snoop servlet should respond with either an authentication prompt, or a message "Error 403: AuthenticationFailed." This is good; it means the snoop servlet is a protected URL. Now, try accessing the servlet with the OAuth token.

Take the access_token parameter value printed to the console from the cURL command and append it as a URL parameter to the snoop URL. In this example, the OAuth access token is "ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua," and so the URL becomes:

https://<server_name>:9443/snoop?access_token=ej3yNolPszGOzyO5FIJ1pExKktnvtE8N26NnCdua

Load this URL in a browser, and the snoop application should now render without problems. In the "User Principal" line at the end of the Request Information section, the servlet should have printed the ID of the user that originally requested the access token, as shown in Figure 6.

Figure 6. OAuth User Principal printed by snoop servlet
OAuth User Principal printed by snoop servlet

If you see a result like this, congratulations! Your OAuth service provider is enabled and fully functional.


Debugging

If you need to debug the OAuth capability, enable all trace messages for the trace string "com.ibm.ws.security.oauth20.*." The most common source of configuration problems is misconfiguration of the TAI for the protected URLs. With trace enabled, the WebSphere Application Server trace.log file will detail where and when the TAI handles (or does not handle) OAuth requests.


Conclusion

This article illustrated the minimal steps needed to enable WebSphere Application Server as an OAuth 2.0 service provider. A whole lot of details you might be wondering about were skipped, such as: How long will the tokens live? Are refesh tokens enabled?, and so on. OAuth as a service provider has many tuning options and deployment considerations.

In brief, this is what you configured:

  • An OAuth service provider enabling the Authorization Grant and Resource Owner Password Credentials flow.
  • Clients stored in base.clients.xml in the oauth20 folder. Be sure to secure client secrets before going into production.
  • Tokens stored in memory. Tokens are backed by a dynamic cache, and the cache is backed by the file system, so the tokens will survive a server restart. Data integrity is maintained by the dynamic cache as long as WebSphere Application Server is properly shut down. Use of a database is recommended when running OAuth in a production environment.
  • Token lifetime of 1 hour.
  • Refresh tokens valid for 1 week.
  • The OAuth provider protecting the "/snoop" URL.
  • All these settings can be modified by changing values in your OAuthProvider.xml file in the oauth20 folder.

As mentioned throughout this article, many advanced OAuth configuration settings are available and the WebSphere Application Server Information Center is the best source for additional details. If you plan to implement OAuth in a highly advanced deployment, take a look at Tivoli Federated Identity Manager, which adds many fine-grained tuning options for an OAuth SSO environment requiring less customization, support for several different types of OAuth enforcement points, and built-in high availability.

Resources

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=877544
ArticleTitle=Using OAuth: Enabling the OAuth service provider in WebSphere Application Server
publish-date=05082013