Header Image

Oracle Entitlements Server Integration

The Layer 7 SecureSpan SOA Gateway acts as a policy enforcement point (PEP), providing the interface to an organization's services and responsible for controlling access.  Often, these authentication and authorization decisions are as simple as performing an LDAP look up (and perhaps verifying some user attribute values) before allowing the request to proceed.

However, when organizations require highly customized, fine-grained access control rules in which it would be cumbersome at best to build a solution using traditional user directory attributes, they turn to purpose-built entitlement engines.  These entitlement engines typically expose interfaces using either standard protocols (often XACML over SOAP) or more proprietary formats, or both.  In deployment architectures such as this, the Layer 7 Gateway can delegate fine-grained entitlement decisions to XACML policy decision points (PDPs) as part of its policy processing. 

In this tutorial we'll show how to configure a Layer 7 policy to delegate access control decisions to Oracle Entitlements Server (OES) via the XACML/SOAP interface that it exposes.

The complete, working policy will look something like this:

Sample Working Policy - Layer 7 Technologies

Lines 2-4 set up our resource, action and environment values as context variables.  These are values needed by the XACML endpoint to make an access control decision and would typically be extracted from the inbound request message.  This information could appear in HTTP headers, URI parameters or elements in the XML payload obtainable via XPath.  For the purposes of this example we'll just hard code the variable values at the beginning of our policy.

Lines 5 through 9 set up variables that will be used in the event of an error and the SOAP fault that needs to be returned.  The four soapFault* context variables can be updated throughout the policy (lines 21 & 32) depending on the current step being executed so that the fault information returned is specific to the step that generated the error.

Fault Response Properties - Layer 7 Technologies

Lines 10-12 indicate the type of credentials required.  In this example policy we require either HTTP Basic or a WS-Security Username Token, but any of the available access control credentials could be used.

A typical pattern for these use cases involves 2 steps, with the first being to authenticate the credentials.  OES returns a session ID in response to a successful authentication call.  This session ID (which has a limited lifetime) is a base64'd string of characters that acts as a single sign on (SSO) token. As part of this policy, the Layer 7 Gateway will cache the session ID for its lifetime.  This session ID is then submitted in the second step of this process which is the authorization call.

At line 13 we branch the policy into two possible execution paths:

  1. The first path (lines 14-18) performs a look up in the cache to see if a session ID already exists for this particular user.  The cache key is the username, which is available as a built-in context variable called request.username.  If the cache look up fails to produce an existing session ID for this particular username, the policy fails this path and falls through to the second path.

    Cache Lookup Properties - Layer 7 Technologies

  3. In the second policy path (lines 19-28), an Authentication call is made to the XACML endpoint with the username/password to obtain a valid session ID. To make this call, we use the Set Context Variable assertion to create an XML request message. In the expression, we place a template of the XACML request expected by OES and populate the dynamic values with the request.username and request.password context variables. This request is then routed to the Authentication service.

 Context Variable Properties - Layer 7 Technologies

An XPath is run on the response to extract the session ID (called ALESIdentityAssertion in OES parlance). If the XPath fails, an appropriate SOAP fault is returned using the fault detail set on line 21. On success, the session ID is cached for subsequent use:

Cache storage properties - Layer 7 Technologies

Once we obtain a valid session ID (either via the cache or the Authentication service call), we can call the XACMLAuthorization service. We'll use the Set Context Variable once again with a template XACML/SOAP request, and populate the dynamic values with those extracted from the inbound request. In this case, the dynamic values are represented by the following context variables: ssoToken, oesResource, oesAction and oesEnvironment.

XACML Authorization service example - Layer 7 Technologies

The final step is to extract the decision from the XACMLAuthorization response message.  We do this once again using XPath to obtain the Decision element value.  We then test it to see if it equals the Permit value we require before proceeding with the request.  If the decision is "not Permit" we will return a Soap fault with the detail configured at line 32.

Congratulations, you now have a working integration between your Layer 7 SecureSpan SOA Gateway and your XACML entitlements engine!  

Note that this is just one simple example of how to build this integration.  We could have made use of the Layer 7 Gateway's Create XACML Request Assertion to build our authentication and authorization calls instead of the Set Variable Assertion.  If your use case requires a more complex XACML request involving several resources and many AttributeValue elements, the Create XACML Request Assertion might prove more helpful.

Additionally, we could have omitted the session ID caching entirely and made the Authentication call for every request.  The options are many and varied, and Layer 7's flexible policy language allows the integration to be built in a way that meets your specific needs.

Oracle Entitlements Server Integration