![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Welcome to the IBM® WebSphere DataPower and OAuth article series. These articles provide an introduction to OAuth and the role that DataPower plays as a policy enforcement point (PEP) and policy decision point (PDP) within OAuth architectures. If you are familiar with DataPower, you are aware of the purpose built nature of these devices and the specialized hardware and firmware that are leveraged to provide highly optimized and secure security, integration, and transformation platforms. We will discuss the latest features supporting OAuth in the 5.0 version release, including integration with IBM's Tivoli® Federated Identify Management V6.2.2 or later products.
Part 1 presents an introduction to OAuth and DataPower support. The articles in the rest of the series are:
- Part 2: Using the Web Token Service in a DataPower OAuth configuration describes how to create, configure, and debug the Web Token Service (WTS). It also explains typical use cases of WTS and the advantages of using WTS over other services. Finally, it provides a sample configuration of WTS.
- Part 3: Using the AAA and form-based login in DataPower OAuth protocol support covers how authentication, authorization, and auditing (AAA) are used to support OAuth protocol, and how to configure form-based login for resource identity authentication processing.
- Part 4: Using DataPower OAuth 2.0 with the resource owner password credential helps you to configure DataPower and enable OAuth 2.0 support using the resource owner password credential grant type. It covers both authorization server and resource server setups.
- Part 5: Using client credentials in a DataPower OAuth configuration covers how to configure DataPower as the OAuth authorization server that issues an access token in a two-legged scenario using client credentials as the grant type.
- Part 6: Using the authorization code grant in a DataPower OAuth configuration describes how to use an authorization code grant type and how to configure DataPower to support it.
- Part 7: Using WebSphere DataPower with Tivoli Federated Identity Manager to support OAuth 2.0 describes how to use a DataPower service to act as an OAuth token enforcement point for a Tivoli Federated Identity Manager OAuth authorization server.
The following articles in the series will be available in the weeks to come:
- Part 8: Customizing DataPower support for OAuth Scope and Identity processing demonstrates how to extend DataPower processing of an OAuth scope and identity.
- Part 9: Customizing the DataPower native support for OAuth authorization codes and access tokens shows how to customize the issuance and verification of authorization codes and access tokens.
- Part 10: Troubleshooting DataPower OAuth protocol support describes tools and techniques for debugging DataPower OAuth configurations.
OAuth is an authorization framework that allows a resource owner to grant permission for access to their resources without the sharing of credentials, and to provide limited access to resources hosted by web-based services accessed over HTTP. This is not to be confused with Web services and service-oriented architecture (SOA). While these architectures exist in a vast array of implementations, OAuth is more focused on the emerging Web 2.0 infrastructure and the popularity of APIs that exist to provide customizable access to an organization's applications. For example, eBay® provides an API to provide enhanced shopping experiences by integrating with third-party applications. Twitter® and Facebook® provide APIs that extend their applications by providing content sharing capabilities. Each of these integrations requires focused attention on all aspects of security and the need to consider all access to be untrusted until proven otherwise.
In established implementations, resources are protected and accessed by providing credentials that can be authenticated, which a resource server can use to authorize access to the resource. If a resource owner wishes to grant access to a third-party, credentials must be provided, authenticated, and access authorized by the authorization service that protects the resources.
These established architectures expose several problems, including the inherit weakness of password authentication. Passwords are vulnerable; a "man in the middle", or perhaps a "woman looking over your shoulder", could obtain your credentials and gain access to your resources. And most likely, a resource owner has to share their password with the entity that needs access. And when a password is changed, the entity no longer has access to the resource. A more fundamental limitation is that authentication and authorization are all under the control of the resource owner, thereby limiting the sharing of authentication information. IT organizations have played an integral part in these security decisions limiting flexibility. Who you are is one component of access control that can be externalized from the authorization process by providing a federation of identity management across organizational boundaries.
OAuth works to address these issues by providing an authorization service separate and apart from the resource owner. Trusted authentication services may be used to provide "tokens" providing access to resources. An OAuth resource owner grants a client access to his or her resources by authenticating with the authentication service and the authorization service that issues service specific access tokens to the third party. In a typical OAuth use case (shown in Figure 1), you (resource owner) may provide a printing service (third-party, the client) access to your pictures (resource) by authenticating to an authentication service and providing limited access (access token).
Figure 1. OAuth print service access token flow
The goals of OAuth are similar in some degree to Security Assertion Markup Language (SAML), published by OASIS. However, as SAML is associated with SOA, and uses XML and SOAP as its protocol foundations, OAuth leverages JavaScript notation. OAuth is flexible enough to work within the JSON modality common within mobile web and Web 2.0 environments.
The current version of OAuth, 2.0, is published in draft form by the Internet Engineering Task Force (IEFT). You may wish to review the current OAuth IEFT documents for additional information.
Now that you have a basic understanding of the goals of OAuth, let's get review some of the terminology. This section describes basic roles, authentication types, and basic flows that happen in the process of obtaining access to protected resources. We have described some of this in our introduction, but let's review them once more:
- Resource owner: An entity (possibly a person or end user) that is capable of granting access to a protected resource.
- Resource server: A process (typically an HTTP server) that is capable of accepting and responding to resource requests and resolving access tokens.
- Authorization server: A process (typically Secure Token Service or STS) that is capable of authenticating a resource owner and issuing access tokens. The authorization service performs multiple functions and, therefore, exposes multiple service endpoints. There are authorization and token endpoints and enforcement points for the resource server.
- Client: An entity making a request for a resource at the approval of a resource owner.
Now let's review the traditional OAuth authorization code grant type protocol flow shown in Figure 2.
Figure 2. Traditional OAuth authorization code grant type protocol flow
The basic flow is straightforward and as we have discussed, the client requests access to a resource from the resource owner, who responds with an authorization grant defining specific access privileges. The resource owner typically uses the authorization server for grant generation. The authorization grant is submitted to the authorization server, which responds with an access token that is used to access the resource from the resource server.
We've discussed the resource owner's "granting" of access rights to its protected resources. The type of grant can vary, depending on the level of trust between the client and the resource owner, the client's relationship to the protected resource, and also by the type of implementation. OAuth has defined two general client types, depending on their ability to maintain the confidentiality of their credentials:
- Confidential: For clients who are capable of maintaining confidentiality of their credentials.
- Public: For those clients who are not capable of maintaining confidentiality of their credentials.
Each client must register with the authorization server prior to engaging in an OAuth protocol exchange. Successful registration results in the establishment of a "client identifier" and other metadata on the authentication server, which the client will use in subsequent interactions.
The authorization code grant is available when the authorization server acts as an intermediary between the confidential client and the resource owner. HTTP redirects are used by the client to direct the resource owner to the authentication server (including its client identifier and intended scope), and in turn, directs the authentication code back to the client. Authentication of the resource owner is accomplished without the sharing of credentials with the client, as well as the direct transmission of the access token to the client without having to traverse through the resource owner.
Implicit grants are available as a simplified method of access token generation for browser-based public clients. Rather than generating the intermediate grant, the access token is issued directly to the client after authenticating the resource owner. While this improves efficiency, it is a less secure method than intermediate authorization code grants, such as the authorization code grant.
The resource owner password credential grants may be used directly by a client to obtain an access token. There must be a high level of trust between them.
Client credentials may be used for authentication and access token generation in instances where the client is the owner of the resource, or is acting on previously existing authorizations. The client may be the resource owner in this instance.
Access tokens provide the resource access rights as well as constraints, such as scope and duration. This token is typically an opaque string, which may take the form of a pointer to retrieve the actual access token or provide self-contained information. Access tokens may take different forms when used to access protected resources:
- A bearer token is opaque data. This requires secured protocols, such as HTTPS, for transmission to protect the token.
- A MAC token uses a supplied MAC key to sign sections of the request for integrity verification.
- Refresh tokens may be issued by the authentication server at access token generation. They may be used by the client to obtain additional access tokens when existing access tokens have expired, or in order to obtain a more limited set of permissions than originally defined.
Two-legged vs. three-legged flows
The scenarios we have describe so far have dealt with the typical OAuth architecture, where a resource owner provides a client (third-party) access to their resources. This is authorized by the authorization service and provided by the resource server. In this "three-legged flow", the resource owner does not want to provide their credentials to the client and, therefore, the client requires an authorization code grant as was demonstrated in Figure 2.
However, the specification also provides for a scenario where the client may be the resource owner, or it can be a trusted entity that has been provided the resource owner's credentials. In this "two-legged" use case, there is no direct resource owner interaction. It requires a resource owner password credential or a client credential grant type.
Now that we have described some of the fundamental aspects of OAuth, let's introduce the capabilities provided by the 5.0 version of the DataPower firmware. Detailed discussions and specific uses cases will be demonstrated in the rest of the article series. For now, we will introduce the supported roles, grant types, new objects, and use cases.
DataPower can act as an OAuth authorization service responding to authorization endpoint and token endpoint requests. DataPower can act as a Policy Enforcement Point (PEP) for a resource server receiving OAuth 2.0 requests. DataPower can integrate with IBM's Tivoli Federated Identity Manager V6.2.2 or greater. Interactions with Federated Identity Manager use the WS-Trust protocol for token verification. DataPower supports bearer tokens with confidentiality and integrity support provided by the underlying secured transport (HTTPS).
New objects and configurations are provided to support OAuth interactions:
- The OAuth Client Profile is a new configuration object used to define the parameters that are used during the registration process, such as client-id, redirection-URL, scope, and lifetime. Authentication forms, shared-secret, as well as the supported grant types and roles that the client will use in subsequent protocol exchanges, are defined here as well. The OAuth Client Group is used to create collections of OAuth clients.
- The AAA Policy has been enhanced to provide OAuth specific capabilities including:
- Extract Identity OAuth Method used to obtain OAuth Client ID and shared secret.
- Extract Resource Processing Metadata used to obtain requested OAuth scope.
- The Web Token Service is a new service configuration object that acts as a token service and as an OAuth authorization service. A wizard is provided to guide you through the creation of policies.
Figure 3 shows the earlier OAuth protocol exchange updated to use DataPower as both an authorization service and as the authentication service for the resource server:
- When acting as the authorization service authorization endpoint, DataPower is producing the authorization grant.
- As the token endpoint, it is producing access tokens.
- When acting as the
enforcement point to protect the resource service, it is validating the
access tokens used to access protected resources.
Figure 3. DataPower acting as an authorization service and enforcement point for a resource server
Figure 4 shows the integration of Tivoli Federated Identity Manager for authorization services. This integration leverages Tivoli's enterprise level federation capabilities.
Figure 4. Integration of Tivoli Federated Identity Manager for authorization services
This article introduced some of the fundamental concepts of OAuth and support provided by DataPower release 5.0. The DataPower appliance products are a time tested, highly secured, and optimized security, integration, and transformation platforms. The feature described allows for the implementation and integration of OAuth protocol exchanges.
For additional information, see the rest of the article series as follows:
- Part 2: Using the Web Token Service in a DataPower OAuth configuration
- Part 3: Using AAA and form-based login in DataPower OAuth protocol support
- Part 4: Using DataPower OAuth 2.0 with the resource owner password credential
- Part 5: Using client credentials in a DataPower OAuth configuration
- Part 6: Using the authorization code grant in a DataPower OAuth configuration
- Part 7: Using WebSphere DataPower with Tivoli Federated Identity Manager to support OAuth 2.0
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
Many individuals contributed to the implementation of OAuth in DataPower. The authors of this article series wish to thank members of the IBM Software Services for WebSphere organization for their contributions, including: Cindy Claudant, Nicholas A. Glowacki, Tamika Moody, and Timothy Baker.
Learn
-
IBM WebSphere DataPower SOA Appliance Handbook
-
WebSphere DataPower library
-
developerWorks WebSphere DataPower zone
-
IETF Web Authorization
Protocol document (oauth)
Discuss
John Rasmussen is a Senior Software Engineer with IBM’s Software Group. He has worked with DataPower Corporation and IBM since 2002 as a product development engineer and services specialist, assisting many clients in the implementation of DataPower appliances. John has experience in software development and security, including work with McCormack & Dodge and Fidelity Investments, and as an independent developer of application software and security systems.
