OAG/OES Integration for Web API Security: skin and guts

Introduction

When it comes to defining a strategy for web API security, OAG (Oracle API Gateway) and OES (Oracle Entitlements Server) together present a very interesting choice and are a very powerful combination indeed.

In this post we're going to take a look at what each component brings in (the skin) and then get our hands on actually describing the integration in detail (the guts).

OAG is designed to inspect and act on various types of messages that are delivered to it or just pass through it. It's usually positioned to be deployed on the DMZ (the De-Militarized Zone) within corporate networks. As such, it can block malicious traffic, authenticate users with a variety of protocols, integrate with anti-virus products, perform message throttling, thus delivering only the good stuff to your intranet servers and also off-loading them, decisively contributing to achieve some IT operational SLAs. More than that, OAG can switch protocols and transform messages. For instance, an organization may have SOAP-based web services and want to expose them as REST without any re-writing. Or implement SAML federation without touching origin systems. Or talk Kerberos or OAuth with clients and speak SAML with back-end servers. Or use it as an FTP server so that incoming files are immediately sent to a processing pipeline. The possibilities are numerous. Having mentioned these few features and examples, it's not unreasonable to think deploying OAG inside intranets. And that's not unusual, actually. It is a nice bridge with obvious benefits.

OES is designed to provide fine-grained authorization with externalized policies to client applications. It takes the coding of access decisions away from developers. Besides the obvious security pro, it shortens the change cycle, when a new security policy needs to be deployed. You simply avoid going through all the phases required for re-deploying your application just because of that change. It's true the new policy needs testing, but that's nowhere near when compared to what it takes to re-deploy a new application version. The time to market is drastically reduced. Now to the fine-grained part. OES can take a bunch of aspects in consideration when authorizing: the user identity, user roles, user attributes, context information about the request being made (like originating IP address), factors external to the request (like time of day, day of week, etc) and, of course, request data. Those combined makes it a very powerful authorization engine. It's not coincidence that OES is the component behind OAM's (Oracle Access Manager) authorization engine.

While OAG itself brings in authorization capabilities, in this field OES offers a much richer model. And if the organization already employs OES elsewhere, integrating it with OAG makes a lot of sense, because we end up with a single and consistent approach for authorization across applications.

Identity Propagation from OAG to REST APIs protected by OWSM

Introduction

This post describes the necessary configuration for propagating an end user identity from OAG (Oracle API Gateway) to REST APIs protected by OWSM (Oracle Web Services Manager).
The requirements are:

1) Have a Java Subject established in the REST API implementation.
2) Prevent direct access to the REST API, i.e., only OAG should be able to successfully invoke it.

A recurrent question is how OWSM protects REST APIs and which types of tokens it supports when doing so.
If we look at the current OWSM (11.1.1.7) predefined policies, we notice a policy named
oracle/multi_token_rest_service_policy, described (verbatim) as:

"This policy enforces one of the following authentication policies, based on the token sent by the client:

HTTP Basic—Extracts username and password credentials from the HTTP header.

SAML 2.0 Bearer token in the HTTP header—Extracts SAML 2.0 Bearer assertion in the HTTP header.

HTTP OAM security—Verifies that the OAM agent has authenticated user and establishes identity.

SPNEGO over HTTP security—Extracts Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) Kerberos token from the HTTP header."

In this specific use case, we are assuming the end user has already been authenticated by some other means before reaching OAG. In other words, we are assuming OAG gets some sort of token
and validates the user locally, thus populating its authentication.subject.id attribute. This token OAG receives can be an OAM token, a Kerberos token, SAML token, you name it. It is matter of
a design decision based on OAG's client capabilities.

In a use case like this, it's very unlikely that OAG will have the end user password, which eliminates the HTTP Basic header option. The remaining three are all good candidates. In this post we deal with a SAML 2.0 Bearer token in the HTTP Header. Our flow ends up being something like this: OAG Client -> "some token" -> OAG -> SAML 2.0 Bearer -> OWSM -> REST API.

We're going to examine all necessary configuration in OAG, OWSM and in the REST API application. Buckle up, folks! And let's do it backwards.

Part 4: Kerberos Authentication, RBAC and SAML identity propagation in OAG

This post is the fourth and last post of a series by Andre Correa and Paulo Pereira on OAG (Oracle API Gateway).

In the first post we introduced the use case and talked about the Kerberos authentication part.

In the second post we talked about Role Based Access Control.

In the third post, we described how to propagate the authenticated user through a SAML token and also covered OWSM configuration in OSB and SOA.

In this post we talk about the client, how we actually submit a Kerberos token along with our request to OAG.

In the first post, we said (verbatim):

“Perhaps the most challenging part was the test client. Supporting Kerberos was a must. Our first and natural attempt was OAG’s API Explorer (formerly OEG Service Explorer). After numerous attempts, configuration changes everywhere, we came to the the conclusion that it simply does not support the SPNEGO protocol properly. In summary, it seems that it doesn’t honor the second leg of the protocol, i.e., after receiving a “WWW-Authenticate: Negotiate” HTTP header in the response, it does not resubmit the request along with the Kerberos token. And we also did not find a way to bypass SPNEGO and submit the Kerberos token directly. The free version of SOAP UI also failed.

Fortunately, via Prasad’s blog post, we came to know a .Net-based tool called WCFStorm-lite, dead simple, that just works. However, another requirement for this exercise was to show test automation best practices. So the client tool should ideally have scripts capabilities, allowing for the client integration into an ANT build script, for example. WCFStorm-lite has some scripts capabilities, but we did not go any further in looking at them, because almost at the same time we got to know Apache CXF’s support for Kerberos.

That basically put an end to our research. What could be better than simply writing a piece of java code? At the heart of Apache CXF’s framework are what they call interceptors, which are basically web services handlers. An inbound interceptor is attached to a web service and processes the message before service invocation. An outbound interceptor is attached to a web service proxy and process the message as it leaves the client. An out-of-the-box Kerberos interceptor interfaces with the KDC, gets a Kerberos token and attaches it to the request before sending it out to the web service (in our use case, a web service exposed by OAG).”

Very well, let’s talk about how to configure a Kerberos Outbound Interceptor in Apache CXF.

Part 3: Kerberos Authentication, RBAC and SAML identity propagation in OAG

This post is the third one of a series by Andre Correa and Paulo Pereira on OAG (Oracle API Gateway).

In the first post we introduced the use case and talked about the Kerberos authentication part.

In the second post we talked about Role Based Access Control.

In this one we describe how to build a SAML token out of the authenticated user and sign it so it properly interoperates with an OWSM server-side policy applied to OSB proxy service. We also cover the necessary OWSM configuration in OSB and SOA. As a reminder, a typical request in our exercise flows through OTD -> OAG -> OTD -> OSB -> OTD -> SOA -> Stub server, and we're required to keep the user identity all the way up to the Stub server.

Now we're specifically talking about the third policy in our overall circuit:



'Add SAML token policy' is as simple as:



We first add the SAML token (using the Insert SAML Authentication Assertion filter), then we sign it (using the XML Signature Generation filter). Let's look at each filter in detail.

Part 2: Kerberos Authentication, RBAC and SAML identity propagation in OAG

This post is the second one of a series by Andre Correa and Paulo Pereira on OAG (Oracle API Gateway).

The first post is found at http://fusionsecurity.blogspot.com.br/2013/03/part1-kerberos-authentication-rbac-and.html. Check it out for use case background and the Kerberos authentication part.

As mentioned, one of the requirements in our exercise was to authorize the user against a ROLE X URI matrix, called “Authorization Matrix”. In this post we’re looking at the second policy (Call ‘Perform Authorization’) in the overall flow:



Basically, “Perform Authorization” had to:

a. Obtain the authenticated user (authenticated by Kerberos);

b. Lookup the groups memberships in Active Directory;

c. For the requested URI, query a Database for the authorized roles for that URI in particular;

d. Check if any of the user groups (obtained from AD) is in the list returned by the DB query;

e. Authorize the user in case the check on the previous steps passes.

Part 1: Kerberos Authentication, RBAC and SAML identity propagation in OAG

This post is the first one of a series by Andre Correa and Paulo Pereira on OAG (Oracle API Gateway).

Throughout the series, we are going to talk about Kerberos authentication, Role Based Access Control (RBAC) and SAML identity propagation in OAG 11g, formerly known as OEG (Oracle Enterprise Gateway). What follows has been implemented as part of a larger exercise involving the SOA suite, OSB, OTD (Oracle Traffic Director) and the Exalogic platform. The kind of architecture presented here can be used as general guidance, but that may not apply to your use case scenarios. We will also briefly touch on OWSM policies that were applied to OSB and SOA composite.

The use case is about enabling end users to place orders. As you might think, there are quite a few 3rd-party systems to interact with in order to have the order fulfilled and the product provisioned to the end user. SOA to the rescue.

Security Requirements

Provide a security shell around SOA and channel each and every request through OAG. The classic model of perimeter defense. As the applications used by end users are Kerberos enabled, the customer wanted to see OAG authenticating Kerberos tokens generated by Active Directory’s KDC (Key Distribution Center). After authentication, we were asked to authorize the user based on a Security Matrix (a relation of groups and URIs) kept in an Oracle database. Finally, with the user properly authenticated and authorized, we should forget Kerberos and instead propagate a SAML token to the SOA platform. This identity should then be preserved all the way to downstream 3rd-party systems.

At the end of our exercise, the policy we built in OAG is expressed as the following circuit, where we can clearly see authentication, authorization and token switch. We expand the contents of each filter/policy as we go. In this post, we focus on the Kerberos Service filter and how we enable the policy for the service we want to protect.

Deployment Architecture

All Oracle FMW components (as well as OAG) were deployed for HA on a 4-node 1/8 Exalogic rack, as per the following diagram.