Using OAuth: Enabling OAuth in the WebSphere Application Server Liberty profile

OAuth 2.0 service provider support was added to the IBM® WebSphere® Application Server Liberty profile as part of WebSphere Application Server V8.5.0.2. This article provides an overview of OAuth support highlighting architecture, new features, and the minimal configuration steps needed to enable OAuth in the server configuration. 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 OAuth 2.0 specification, OAuth 2.0 service provider capability was added to the Liberty profile in IBM WebSphere Application Server V8.5.0.2. The OAuth feature must be enabled in the server definition in order to take advantage of this capability.

This article covers the key steps required to configure the WebSphere Application Server Liberty profile 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 and the Liberty profile is also assumed, specifically with regard to installing the Liberty profile, creating a server, and updating the server configuration.

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

  • WebSphere Application Server V8.5.0.2
  • Liberty profile.

High-level architecture and features

First, here is a brief overview of the OAuth implementation in the WebSphere Application Server Liberty profile to help you understand how the configuration steps affect WebSphere Application Server. This information is also helpful in debugging and tuning the configuration settings. Although users familiar with OAuth in the full profile will likely find OAuth in the Liberty profile easy to configure and use, the OAuth capability in the Liberty profile has several important differences from the full profile.

The Liberty profile provides OAuth service provider support as a single run time security service (Figure 1). OAuth configuration is defined in the server configuration file, and this is the only piece required to enable OAuth in the Liberty profile. Once an OAuth server is defined in the server configuration file, the server will activate the pieces needed for OAuth support, such as endpoint servlets and the authorization module. With the Liberty server's dynamic update capability, run time changes can additionally be made directly to the server configuration file, eliminating the need for multiple configuration interfaces.

Figure 1. Security in the Liberty profile
Security in the Liberty profile

Referring to the numbers in Figure 1, here are the web application security steps in the Liberty profile:

  1. A client requests a web resource.
  2. The web container delegates the security check to the Web Security Collaborator (glue code).
  3. The Web Security Collaborator prompts the user to enter his credentials (if absent) and uses the authorization service to authenticate he user.
  4. The authentication service authenticates, creates, and returns the subject.
  5. The Web Security Collaborator uses the authorization service for user authorization check.
  6. The authorization service returns the authorization result to the Web Security Collaborator.
  7. The Web Security Collaborator returns the result of the security check (true or false).
  8. The web container serves or rejects the requested resource.

OAuth components include:

  • OAuth runtime: Controller for the OAuth data and endpoints.
  • Liberty server.xml: Defines the OAuth configuration, used for registering new clients, and single-point configuration.
  • 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-related features available in the WebSphere Application Server Liberty profile 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.
  • Multitenancy support for multiple OAuth providers, differentiated by endpoints and data segregation.
  • XML file or database storage of tokens and clients.
  • Configuration through server XML editing.
  • Customizable servlet UI.
  • Sample configuration files.
  • Token revocation by administrators or users.
  • Reconfiguration without need for server restart.
  • Configurable authentication handling, including per-provider protected URLs and token handling.
  • Advanced rules syntax for defining authentication parameters.

While the WebSphere Application Server Liberty profile 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. For advanced setup information, see the WebSphere Application Server Information Center.


Enabling the OAuth provider

Step 1: Initial setup

  1. Ensure that your version of WebSphere Application Server matches the minimum levels listed above.
  2. Install the Liberty profile and create a server (if you haven't already done so). To create a new server in Liberty go to the <liberty_root>/bin folder and run server create <server_name>. In these examples, the server name "oauthServer" is used.
  3. When the server is available, several setup steps are required to prepare the server for OAuth capability:
    1. Enable security, SSL, and application security features, required for the OAuth feature and to protect applications.
    2. Install a test servlet to validate OAuth functionality.
    3. Enable JSP and servlet features for the test servlet.
    4. Enable a user registry for test users.
    5. Enable HTTP endpoints for testing.

    Each of these pieces can be enabled with a few configuration lines in the server.xml definition file for your server. Find this file at <liberty_root>/usr/servers/<server_name>/server.xml and open it in an editor to make these changes:

    1. In the <featureManager> section, add all of the features in Listing 1 that are missing from your server definition. These updates will enable features required by OAuth and the test servlet.
      Listing 1.
      <featureManager>
      	<feature>jsp-2.2</feature>
              <feature>security-1.0</feature>
              <feature>appSecurity-1.0</feature>
              <feature>servlet-3.0</feature>		
              <feature>ssl-1.0</feature>
              <feature>oauth-2.0</feature>
      </featureManager>
    2. Update the httpEndpoint with the machine hostname to handle requests for remote testing, if desired, and make sure an HTTPS port is defined (Listing 2).
      Listing 2.
      <httpEndpoint id="defaultHttpEndpoint"
      	host="example.com"
      	httpPort="9080"
      	httpsPort="9443" />
    3. Add a keyStore to enable SSL. The password should be encrypted if running the server in a secure (non-developer) environment:
      <keyStore id="defaultKeyStore" password="insecurePass" />
    4. Use the securityUtility command to encrypt the password for secure environments. (See the securityUtility documentation for details.)
    5. Add some sample users for testing, if no other registry is configured (Listing 3).
      Listing 3.
      <basicRegistry id="basic" realm="customRealm">
      	<user name="test1" password="test1" />
      	<user name="test2" password="test2" />
      	<user name="test3" password="test3" />
      </basicRegistry>

    At this point the server is enabled with the minimum set of prerequisite features required for OAuth support and validation. At a minimum, the server.xml file would have all the pieces shown in Figure 2.

    Figure 2. Minimal server preparation
    Minimal server preparation
  4. The other side of setup involves installing an application that OAuth will protect. You might already have a servlet in your environment that you would like to protect for testing. If not, download the testpage.ear included with this article. This is a tiny test servlet application that you can use to validate OAuth functionality. Copy this test application into the <liberty_root>/usr/servers/<server_name>/dropins folder. The testpage application sets security role bindings for ALL_AUTHENTICATED_USERS, so any user should be able to login and access the application.
  5. Next start the server, and open a browser to the endpoint https://<server_name>:<port>/testpage. In this example, the URL is https://example.com:9443/testpage.
  6. The browser should prompt for authentication. Login using one of the users defined in the basicRegistry. The page should print the ID of the user that just logged in.

Areas to check if your URL does not prompt for authentication:

  • If accessing the server from a remote machine, ensure in the httpEndpoint parameter "host" that you have replaced "localhost" with the machine hostname.
  • If the server response with a 404 Not Found message, make sure you put the testpage.ear in the server's dropins folder, and make sure your context root is /testpage.
  • If the page loads but does not prompt for authentication, check that the appSecurity1-0 feature is enabled.
  • If you still have problems, check the server's messages.log file.

If you were able to log into the test servlet and have the servlet print the user ID, the server and test app are now ready for OAuth configuration.

Step 2: Enable an OAuth Provider

For a basic OAuth service provider, all configuration parameters can be added to the server.xml definition. Only two steps are needed in addition to the setup steps described above:

  1. Enable OAuth system-wide: To enable OAuth system-wide, add the oauth-2.0 feature to the existing feature set in the <featureManager>. That is the only feature requirement for OAuth.
  2. Define an OAuth provider: To define an OAuth provider, add an <oauthProvider> section to the server.xml file. The oauthProvider definition enables a large number of configuration parameters to match your desired environment. For the basic configuration described in this article, only a minimal set of configuration parameters will be used. (For additional options and capabilities, see the WebSphere Application Server Information Center topic, "OAuth full profile provider configuration equivalents".)

You will use these OAuth configuration options to protect the test servlet:

  • OAuth provider ID, in this example "DemoProvider." The ID will be used to generate OAuth token and authorization endpoint URLs, so a meaningful ID should be chosen. Be aware that OAuth IDs are case-sensitive.
  • A filter parameter, in this case to protect the testpage context-root use the filter parameter "request-url%=testpage."
  • oauthOnly="false", an optional parameter to enable the testpage context root to continue using basic authentication in addition to OAuth.
  • grantType="authorization_code,password,refresh_token", to enable the common Authorization Code three-legged OAuth flow, as well as the Resource Owner Password Credentials flow for easy testing. As a security best practice, unused flows should be disabled after testing.
  • mediatorClassname=" com.ibm.ws.security.oauth20.mediator.ResourceOwnerValidationMedidator", to validate Resource Owner Password Credentials token requests against the configured user registry.
  • libraryRef="myLib", or the library name of your choice, as the JAR file that contains the mediatorClassname

To define an OAuth provider with these parameters, use the definition shown in Listing 4.

Listing 4.
<oauthProvider id="DemoProvider"
   filter="request-url%=testpage"
   oauthOnly="false"
   grantType="authorization_code,password,refresh_token"
   libraryRef="myLib"
   mediatorClass-name=
"com.ibm.ws.security.oauth20.mediator.ResourceOwnerValidationMedidator">
</oauthProvider>

The OAuth client needs to be defined. Clients can be defined as <localStore> entries within the <oauthProvider> definition (Listing 5).

Listing 5.
<localStore>
	<client name="LibertyRocks" secret="AndMakesConfigurationEasy"
		    displayname="Test Client for OAuth"
		    redirect="http://example.com/oauthclient/redirect.jsp"
		    enabled="true">
	</client>
</localStore>

The name, secret, and displayname fields are values that you select based on your desired client attributes. 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. It will be based on the configuration of your OAuth client. (Because the client credentials flow is used for validation here, the redirect value is not required to accurately reflect the client URL.)

For security reasons, client passwords should not be stored in cleartext. They should be encrypted and stored using the WebSphere Application Server pluggable encryption capability.

As a final enablement step, add a <library> reference to the mediator that will be used for user validation during the OAuth password flow. The default mediator is included in Liberty's oauth20.jar (Listing 6).

Listing 6.
<library id="myLib">
	<fileset dir="<path_to>\wlp\lib" 
	includes="com.ibm.ws.security.oauth20_1.0.jar" />
</library>

Setup is now complete. The Liberty server has a new test application with application security enabled, an OAuth provider defined, and a test client to use with the provider. Your server.xml file should contain all the pieces shown in Figure 3.

Figure 3. Full settings for basic OAuth configuration
Full settings for basic OAuth configuration

Step 3: Validate OAuth functionality

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

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

Because this article focuses on only the Liberty portion of configuring OAuth, steps to configure and use an OAuth client are not covered. 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 his 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, cURL you can download cURL directly.)

Using cURL, run the HTTP POST to the token endpoint, using the resource owner password credentials grant type 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 7 and 8, respectively.

Listing 7.
curl -k -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=password&client_id=LibertyRocks&client_secret=
AndMakesConfigurationEasy&username=test3&password=test3"
https://example.com:9443/oauth2/endpoint/DemoProvider/token
Listing 8.
{"access_token":"C215IX7HyH8DB9Ix7ftHHzYDN4vVfMPZRXrYREUz","token_type":
"bearer","expires_in":3599,"scope":"","refresh_token":
"zehCHVZWPnpFiK9YqfmHeiMRUe4q7rmQRyrSYtMWkMUOzomBLa"}

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 Liberty server logs might also contain an error explanation.

If you are familiar with configuring and testing OAuth providers in the WebSphere Application Server full profile, you might have noticed the validation steps are identical between the Liberty profile and the full profile. This is deliberate. Because OAuth is an open specification, the behavior of the OAuth service providers should be consistent across implementations.

Unlike token requests, when accessing a protected endpoint with the access token, the access token can be provided 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 testpage servlet installed on the server, at https://<server_name>:9443/testpage.

If the page loads, your browser might be storing the credentials from a prior login. If so, clear your session cookies, or try another browser which has not already authenticated with WebSphere Application Server.

The testpage should respond with an authentication prompt. Just cancel out of the prompt, and then try accessing the testpage 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 testpage URL. In this example, the OAuth access token is "C215IX7HyH8DB9Ix7ftHHzYDN4vVfMPZRXrYREUz", and the URL becomes:

https://<server_name>:9443/testpage?access_token=C215IX7HyH8DB9Ix7ftHHzYDN4vVfMPZRXrYREUz

Load this URL in a browser, and the testpage application should now render without problems. In the "current user" section at the end, the servlet should have printed the ID of the user that originally requested the access token, as shown in Figure 4.

Figure 4. OAuth user principal printed by test app
OAuth user principal printed by test app

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 filter for the protected URLs. With trace enabled, the Liberty profile logs will detail where and when OAuth handles (or does not handle) OAuth requests.


Conclusion

This article illustrated the minimal steps needed to enable the WebSphere Application Server Liberty profile as an OAuth 2.0 service provider. We skipped over a whole lot of details that you might already be wondering about, such as: How long will the tokens live? Are refresh tokens enabled? and so on. OAuth as a service provider has a large number of 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 flows.
  • All configuration settings in the server's server.xml configuration file. Be sure to secure client secrets and SSL keys before going into production.
  • Token lifetime of 1 hour, default setting.
  • Refresh tokens valid for 1 week, default setting.
  • The OAuth provider protecting the "/testpage" URL.
  • All these settings can be modified by changing values in your server.xml file.

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.


Download

DescriptionNameSize
Code sampletestpage.ear47 KB

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=877545
ArticleTitle=Using OAuth: Enabling OAuth in the WebSphere Application Server Liberty profile
publish-date=05082013