Thursday Jul 04, 2013

Protecting ADF resources with Oracle Entitlements Server 11gR2 - Part 2

In my last post "Protecting ADF resources with Oracle Entitlements Server 11gR2" I attempted to outline the basic principles of protecting ADF resources using Oracle Entitlements Server 11gR2. In this post I will dive straight into how to configure simple ADF resources with OES policies in a step by step guide.

I need to stress that this is not an official Oracle guide or something that is supported through Oracle. The guide and any sample in this blog are my views and intended as a pointer to anyone looking to integrate OES and ADF.

So, lets configure our components....

Configuring SM Interceptor Mode

The following steps outline the high level configuration steps for creating the WebLogic Security Module in interceptor mode and OES proxies to protect ADF resources.

The high level steps are:

1 – Create the SM Domain

2 – Configure the OES Authorisation Proxy

3 – Configure the OES Role Mapper

4 – Create the OES Application Policies

Create the SM Domain

Follow the steps below to create a WebLogic SM JRF Domain.

Configure the OES Authorisation proxy

Create an OES Authorisation Proxy as a WebLogic authorisation provider within the WebLogic SM domain’s default security realm.

Security realms->myrealm->providers->authorization

OES Authorization Proxy

· Click New

· Enter a name for the provider

· Select OES Authorization Proxy from the dropdown.

Configure the OES Role Mapper

Create an OES Role mapper Proxy as a WebLogic role mapper provider within the WebLogic SM domain’s default security realm. This must be configured for the SM to be enabled as the PEP.

Security realms->myrealm->providers->role mapping

OES RoleMapper Proxy

  • Select the Role Mapping ta
  • Create a new Role Mapper
  • Select OES RoleMapper Proxy from the dropdown

Configure OES Policies

OES policies need to be created to protect the ADF resources handled by the OEA authorisation proxy.

Some points to note about the relationship between OES policies and the OPSS policy definitions that protect ADF resource.

  • ADF security framework polices (as seen in the jazn-data.xml) do not map directly onto OES policies.
  • ADF/OPSS policies utilise pattern matcher classes to define the resource types of the protected ADF resources.
  • The ADF/OPSS resource names are generated by the JDeveloper / ADF application. These need to be translated into the OES policies.

TIP – Configure ADF security in JDeveloper, including resources to protect to get details of the resource names, pattern matching classes etc. These will be detailed in the JDeveloper jaxn-data.xml file and will serve as a reference for you to create the OES policies.

Create OES Application & Security Module

Within the OES administration console, create a new application (see later section for a reference to creating the OES policy resources)

NB* Ensure that the application name matches the deployed ADF application name.

Create Resource Types

Resource types within the OES policy are used to define the pattern match class that will be used to identify the resource type during authorisation.

1. Select New Resource Type from the home tab

2. Enter a resource type name (any name will do)

3. Create actions and attributes as required

4. Change the Evaluation Logic dropdown to “Permission Class”

5. Enter the full permission class name. This can be found in the jazn-data.xml file, if you have enabled ADF security in JDeveloper (example below)


6. Select comma for the action delimiter

Figure 8 - Resource Type

Resource types should be defined as a cross wave activity. The resource types should be common across all ADF applications and their resources that require protecting.

Create the resource

Create the OES resource as the resource name that can be found in the jazn-data.xml file if you have enabled ADF security in JDeveloper. (See example below)


Create the Authorisation Policy

Create an authorisation policy (see guidance steps in section 4.4)

Bind the application to the SM

Bind the application the Security module (see guidance steps in section 4.4)

Deploy the application

Deploy the application to the SM domain.

NB* Ensure that you select the following security configuration when deploying the application:

Advanced: Use a custom model that you have configured on the realm's configuration page.

WebLogic PDP

When using the WebLogic Security Module purely as a PDP, (i.e. the SM is only providing authorisation decisions, but not enforcing them), then we must define the application itself to be the policy enforcement point.

The implications of this are that the application must provide programmatic enforcement of policy decisions that are being returned from the PDP. This could be implemented as a “security bean” which provides an isAuthorised() method which can be called with ADF Expression language (EL), passing the resource identifier for the resource to be protected. The Security bean interacts with the security module to obtain a policy decision based on the parameters that have been passed. ADF pages would be protected via a phase listener providing the authorisation call to the security bean.

The security bean should provide a generic interface which relies on the calling component to set the context of the application and resource to be protected.

The diagram below describes the ADF application components and their interactions with the WebLogic Security Module.

Configuring OES

The following section gives guidance on the components and configuration required to set up an OES environment for development and testing.

The sections define the following:

  • Installing the Oracle Entitlements Server product
  • Creating an OES Administration Server
  • Creating the domain which will contain the WebLogic security Module
  • Creating a test policy to test the configuration
  • Examples of integrating ADF components with OES

Installing OES

1 - Download the binaries for Oracle Entitlements Server 11gR2

2 - Use the following guide for installation.

The guide will take you through the download, installation and configuration of all the required components for getting the base install and configuration.

**NB - Please follow the guide provided in the following link up to and including “Installing the OES Client”

**NB – Ensure that the OES client install is created in a separate directory on the FMW home (do not take the default OES Client install location) e.g. create a OES_CLIENT directory under FMW_HOME.

3 - Use the following sections to guide you through patching and the creation of the WebLogic Security Module.

Installing OES Patches

1 - The following patch should be installed

2 - Download Oracle Identity Management Suite Bundle Patch from ARU/METALINK (

3 – Follow the instructions on the README file for the patch.

Creating OES WebLogic Security Module

The following section is a guide to configuring the WebLogic Security Module. This has been called out separately from the above installation guide as there are a couple of additional steps that are not well documented in creating the Security Module for a JRF (Java Required Files) domain.

Step 1 - Under <OES_CLIENT_HOME>/oessm/SMConfigTool

  • copy smconfig.prp to JRFsmconfig.prp
  • update the following properties
    • Change policystore.type to DB_ORACLE
    • Change sm_name to <SECURITY_MODULE_NAME>

Step 2 - Under <OES_CLIENT_HOME>/oessm/bin

  • Run SMConfigTool with the following command:

config -onJRF -smType wls -onWLS -smConfigId [SECURITY_MODULE_NAME] -serverLocation <FMW_HOME>\wlserver_10.3 –prpFileName <OES_CLIENT_HOME>\oessm\SMConfigTool\JRFsmconfig.prp

3 - This will now launch the Fusion Middleware Configuration Wizard where you should follow the steps in the guide from section 3.1 in this document noting the following:
  • Select Oracle Entitlements Server Weblogic Security Module on JRF
  • Ensure correct JDK location, Update Listen port and SSL listen port choose ports different from any existing/previous domain.

4 - Ensure that your datasources are set up correctly in the WLS SM domain
  • Start up your new SM domain.
  • Create 2 datasources in the client SM domain both pointing to the DEV_OPSS schema that you configured with RCU, and specified within the OES installation. Create two separate identical datasources with the following jndi names.
    • jdbc/APMDBDS
    • jdbc/OPSSDBDS

** NB ** make sure that the datasource that you configure are:

  • Non XA
  • Have “supports global transactions” disabled

5 – Re-configure the SM to support “Distributed-Push” policy distribution
  • CD <OES_CLIENT_HOME>/oes_sm_instances/<SM_NAME>/bin
  • Run oessmconfig.bat -jpsconfig <SM_DOMAIN>\config\fmwconfig\jps-config.xml
  • This will start up the SM configuration tool. Change the following:
    • In the “SM Configuration” tab select “Controlled-Pull” as the policy distribution mode
    • Select the “Policy Store” tab
    • Select “Database configuration through JINDI name”
    • Enter the Datasource JNDI name (“jdbc/APMDBDS”)
    • Enter the “Farm Name” “cn=<OES_ADMIN_DOMAIN>” e.g. cn=oes_admin
    • Enter the “Root Name” as cn=jpsroot
    • Select “Save and Close”
6 – Re-start the SM domain

Creating a test configuration

The previous steps created the Security Module, the following steps intend to outline the steps to create a test configuration to test the security module.

The following steps are detailed in the following guide:

The following steps are outlined in the “Creating OES Administration Policies” please follow these steps exactly as defined in the document.

The high level steps in creating this policy are:

1 - Log into OES Admin

2 - Create a new Application

3 - Create a new Resource Type

4 - Create a new Resource under the Resource Type

5 - Create a new Authorization Policy

6 – Create the definition of the Security Module (SM) in OES Admin UI

7 - Bind the application to previously created SM.

8 - Distribute policy changes

If you have followed the steps above you should see the HelloOESworld application bound to the physical SM when you distribute the policy as below:

Figure 10

The above steps have configured the following policy:

Application: HelloOESworld

Resource Type: MyResourceType

Resource: MyResource

Policy: MyAuthorizationPolicy

2.4.1. Running the test

The following test web application will make a call to the WLS SM with the application and resource details to seek an authorization decision based on the resource and user.

- Download Sample Application 

1 - Deploy the application to the domain containing your SM.

2 – Run the application

  • Open a browser and run the application with the following :
  • The following page should be displayed
  • Changing the policy details on the OES admin server (e.g. changing the userLevel string in the policy to “employee”) should result in a DENIED message. Example below:


Official Oracle OES pages.

OES whitepaper (Good technical introduction & guide)

Tutorial Guide on installing and configuring OES (NB* this is for a Security Module on a non JRF domain, so don’t use the SM config as indicated. See other docs for SM configuration on a JRF domain)

Protecting ADF resources with Oracle Entitlements Server 11gR2

Many organisations are looking for a managed, centralised policy security store to manage fine grained authorisations across their application estate. 

Oracle Entitlements Server (OES) provides that centralised policy management which gives real time policy based authorisation decisions.

I want to look at getting OES policies to protect ADF resources and what options we have for integrating the two for fine grained authorisation.

As an aside, Authorisation...Authorization, potato...potato... I was brought up in England and almost all of the "zation" type words are spelled with as in "organisation". My spell check does not understand but I'll carry on regardless!

To start with, take a look at this white paper that gives a great succinct(ish!) overview of OES:

The first part of this post will outline the high level, how OES can be configured to protect ADF resources. In a second post, I will provide instructions on how to set up a simple ADF application with OES fine grained authorisation.

ADF Security

We first need to understand the ADF security model, from this we can look at how OES will fit into the mix of securing ADF resources.

ADF has it's own security framework that uses Oracle OPSS (Oracle Platform Security Services) policy driven security framework to provide declarative security for ADF resources (taskflows, regions, etc.). OES also uses OPSS as it's underlying security framework, this is key to having these products working together.

Describing the ADF security model is beyond the scope of this blog, but take a look at the many great resources that give an in depth view of the ADF security framework and how ADF resources are protected via ADF policies. A good place to start is with Frank Nimphius's excellent article "Security for Everyone"

OES WebLogic Security Module Authorisation Engine

I want to explain the role of the WebLogic Security Module (SM) and it's place in securing ADF resources. The WebLogic SM is a plugin for OES that enables the WebLogic application server container to provide both Policy Decision Point (PDP) and Policy Enforcement Point (PEP) integrations into OES.  The SM acts as a local authorisation engine that caches OES policies and provides authorisation decisions in the local application server without needing to communicate back to the OES admin server for policy decisions.

NOTE - In the 11gR1 OES release, the WebLogic SM could not be installed within a server domain which had Java Required Files (JRF) enabled. An ADF application needs to be deployed into a WebLogic server domain which has JRF enabled. Due to this, we cannot deploy an 11gR1 SM into the same domain as an ADF application. (An 11gR1 SM needs to be deployed in a separate domain and integrated using REST APIs) 

OES 11gR2 allows the WebLogic SM to be deployed within a JRF domain and hence enables us to deploy the SM within the same server domain as our ADF application.

OES Background & Terminology

So, to give some context, let's outline some basic OES terminology and high level principles. The diagram below shows the high level architecture blocks that comprise Oracle Entitlements Server. I am not going to go into all of these but will give a brief description of the important parts we need in securing ADF resources.

Administrative Server

The OES administration server gives us a GUI console to (amongst other things) manage our policies, applications and distribution of the policies to the security modules.

  • Provides the capability to manage authorisation policy creation, management and distribution.
  • The administrative server is deployed as a J2EE application on WebLogic Server, within its own domain.

Policy Store

The policy store is the place where we store our policy that we define with the OES administration server GUI.

  • The repository for OES policies.
  • The policy store holds the central policy details that is written and read from the administration server.
  • The policy store can be file, LDAP or DB.

Identity Store

The identity store provides us with a credential store from which we can integrate identities, groups, roles etc.

  • e.g. Oracle Internet Directory Server or Active Directory

Authorisation Engine

The authorisation engine is used by OES to make policy decisions and apply policy enforcement on behalf of a requesting application
  • The authorisation engine within the context of managing ADF applications will be a WebLogic security Module, providing the Policy Decision Point and Policy Enforcement Point.
  • A WebLogic Security Module is deployed within each of the managed server nodes in a WebLogic cluster that hosts the application.
  • The security module provides a local cache of policies distributed by the OES administrative server.

What is a PDP?

A PDP (Policy Decision Point) is a component of OES that interacts with the OES policy store to provide a policy decision. For example, given a the details of a resource to protect, principle and other attributes, the PDP will return a DENY or PERMIT decision based on the configured policies.

What is a PEP?

Whereas a PDP will return a PERMIT or DENY response to a resource request, the PEP (Policy Enforcement Point) will actually enforce the decision to allow or deny access to the resource. For example, a PEP may be a web application that takes the PDP response and blocks a user from accessing a page that has returned a DENY from the PDP.

WebLogic Security Module as a combined PDP and PEP

The OES WebLogic Security (SM) module can act as both a PDP and a PEP. Both returning policy decisions and also enforcing them. The security module operating in this way is called interceptor mode.

The WebLogic Security Module plugs directly into the application server that contains the deployed application which is to be protected. The SM intercepts authorisation requests makes the decision and also enforces the decision.
The figure below outlines the role of the SM as a PDP and PEP.

The main customer use case for operating in interceptor mode is to enforce both course and fine grained ADF application entitlements through OES policies. This moves the authorisation policies from application defined ADF Security Framework into policies defined centrally by OES.

 For further details on this configuration refer to

WebLogic Security Module as a PDP

Certain use cases cannot be met through the use of the SM in interceptor mode. Examples of these are, custom code requests that do not use the WebLogic container for authorisation or providing authorisation for certain ADF components (e.g show an ADF button)
To satisfy these use cases, we need the SM to act as a PDP only, and delegate the enforcement to the calling application.

The figure above outlines the components and authorisation flow when using the WebLogic Security module as a policy decision point.
The ADF application will act as the PEP but delegate the authorisation decision to the security module PDP.
When a Security Module acts purely as a PDP, its only functionality is decision making. It receives an authorisation request and returns its decision to the PEP that originally made the authorization call. With the Security Module acting solely as the PDP, an external entity must act as the PEP - make the authorization call (using the Oracle Entitlements Server authorisation API) and enforce the returned decision.

The above figure outlines the high level integration of ADF components with the WebLogic Security Module.

  • The ADF application implements authorisation API calls where required:
    • Phase listeners
    • Backing Beans
    • ADF component expressions.
  • API authorisation request made to SM
  • SM queries local policy cache to return a permit/deny response to the application

Integrating OES and ADF

The following section outlines the high level integration design for integrating ADF components with OES authorisations using two SM modes:

  • WebLogic SM in interceptor mode
  • WebLogic SM as PDP

WebLogic SM in Interceptor Mode

The WebLogic SM can be used to provide container based course grained authentication. The SM, in interceptor mode can be used to automatically protect ADF pages, taskflows, regions and other ADF components via OES policies.

The OES Authorisation Proxy is configured as an authorisation provider within the application server and performs container based authorisation and enforces policy decisions.

The following diagram outlines the WebLogic OES Proxy function

  1. Web browser (user) requests another web page
  2. WLS container examines Browser Cookie and knows the user was previously authenticated. It retrieves the user’s authenticated identity from cache. Then, the container uses the authenticated identity and makes an authorization request for the web page.
  3. OPSS-CSS makes the corresponding call to WLS OOTB authorization provider
  4. The authorization provider sends the response (permit/deny)back to OPSS-CSS framework
  5. OPSS-CSS framework then calls into the OES Authorization Proxy
  6. OES Authorization Proxy forwards the authorization request to OES PDP
  7. OES PDP computes the authorization decision (permit/deny) and sends back the response
  8. OES Authorization Proxy sends the response (permit/deny) back to OPSS-CSS framework
  9. OPSS-CSS framework combines the individual authorization results (permit/deny) from WebLogic Authorization Provider and OES Authorization Proxy and sends the final response (permit/deny) to the WLS container.
  10. The container requests the web page from the web application
  11. The application returns the web page to the container
  12. The container sends the response to the web browser

In my next post (which will appear very shortly) I will provide some step by step instructions on how to configure protection for ADF resources using the WebLogic SM as a PEP.


Welcome to my blog, a space for me to share information on various Oracle middleware technology issues. My day job as an architect within UK Oracle Consulting enables me to look at solutions for a wide variety of issues and I will share some of these issues and solutions here in the hope that it will help you out some day!


« July 2016