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.

Monday Jun 24, 2013

Notes on Oracle BPM PS6 Adaptive Case Management

I have recently been looking at the  latest release of the BPM Case Management feature in the Oracle BPM PS6 release. I had put together some notes to help me gain a better understanding of the context of the PS6 BPM Case Management. Hopefully, this along with the other resources will enable you to gain a clear picture of the flexibility of this feature.

Oracle BPM PS6 release includes Case Management capability. This initial release aims to provide:

  • Case Management Framework

  • Integration of Case Management with BPM & SOA suite

It is best to regard the current PS6 case management feature as a case management framework. The framework provides the building blocks for creating a case management system that is fully integrated into Oracle BPM suite. As of the current PS6 release, no UI tooling exists to help manage cases or the case lifecycle.

Mark Foster has written a good blog which outlines Case Management within PS6 in the following link. I wanted to provide more context on Case Management from my perspective in this blog.

PS6 Case Management - High level View

BPM PS6 includes “Case” as a first class component in a SOA Suite composite. The Case components (added to the SOA Composite) are created when a BPM process is assigned to a case in JDveloper.

The SOA Case component is defined and configured within JDevloper, which allows us to specify the case data structures and metadata such as stakeholders, outcomes, milestones, document stores etc.

"Activities" are associated with a case, and become available to be executed via the case apis. Activities are BPM processes, Human Activities or Java call outs.

The PS6 release includes some additional database tables to store the case metadata and case instance data (data object, comments, etc…). These new tables are created within the SOA_INFRA schema and the documents associated with that case into a document repository that is configured with the case.

One of the main features of Case Management is the control of the case logic through case events and case business rules. A PS6 Case has an associated business rule component, which can be configured to control the availability and execution of activities within the case. The business rules component is able to act upon events that the PS6 Case Management framework generates during the lifecycle of that case. Events are fired during the lifetime of the case (e.g. Case created, activity started, activity ended, note added, document uploaded.)

Internal Case state

The internal state of a case is represented by the diagram below. This shows the internal states and the transition paths for a Case from one state to the next

Each transition in state will create an event that can be enacted upon via the Case rules engine.

The internal case state lifecycle is defined as follows

Defining a case

A Case is created and defined as a component of a JDeveloper BPM project. When you create a Case as part of a BPM project, JDeveloper, creates the following components within the SCA composite:

  • Case component
  • Case component interfaces (WSDL etc)
  • Case Rules component (Oracle Business Rules)
  • Adds the Case Component and Case Rules Component to the BPM SOA composite

Case Configuration

The following section gives a high level overview of the items that can be configured for a BPM Case.

Case Activities

A Case is associated with a set of activities that are to be performed as part of that Case. Case activities can be:

  • SOA Human Tasks
  • BPM processes
  • Custom Task (Java Class)

Case activities are created from pre-existing BPM process or human tasks, which, once defined, can be configured additionally as Case activities in JDeveloper and made available within the lifecycle of a case.

I've described the following configurable components of a case (very!) briefly as:


  • Milestones are (optional) user defined logical milestones that can be achieved within a case.
  • No activities are associates with a milestone, but milestone attainment can be programmatically set and events raised when milestones are reached


  • User defined status of a completed case. An event is fired when an outcome is attained.

Case Data

  • Defines the data that will be stored with a case
  • XML schemas define the data that is stored with the case.

Case Documents

  • Defines the location of documents that are attached to a case (e.g. WebCenter Content)

User Defined Events

  • Optional user defined events that can be fired or captured to drive case processing rules


  • Defines the actors who can participate in the case (roles, users, groups)
  • Defines permissions for individual case permissions (read case, create document etc…)

Business Rules

  • Business rules are the main component controlling the flow of a Case
  • Each case has an associated business ruleset
  • Rules are fired on receiving Case events (or User defined events)
    • Life cycle events
    • Milestone events
    • Activity events
    • Data events
    • Document events
    • Comment events
    • User event

Managing the Case

Managing the lifecycle of a case is achieved in two ways:

  • Managing case logic with Business Rules
  • Managing the case lifecycle via the Case APIs.

A BPM Case can be viewed as a set of case data & documents along with the activities that can be performed within a case and also the case lifecycle state expressed as milestones and internal lifecycle state.

The management of the case life is achieved though both the configuration of business rules and the “manual” interaction with a case instance through the Case APIs.

Business Rules and Case Events

A key component within the Case management framework is the event model. The BPM Case Management solution internally utilizes Oracle EDN (Event Delivery Network) to publish and subscribe to events generated by the Case framework.

Events are generated by the Case framework on each of the processes and stages that a case instance will travel on its lifetime. The following case events are part of the BPM Case:

    • Life cycle events
    • Milestone events
    • Activity events
    • Data events
    • Document events
    • Comment events
    • User event

The Case business rules are configured to listen for these events, and business logic can be coded into the Case rules component to enact upon an event being received.

Case API & Interaction

Along with the business rules component, Cases can be managed via the Case API interfaces. These interfaces allow for the building of custom applications to integrate into case management framework. The API’s allow for updating case comments & documents, executing case activities, updating milestones etc.

As there is no in built case management UI functions within the PS6 release, Cases need to be managed via a custom built UI, interacting with selected case instances, launching case activities, closing cases etc. (There is expected to be a UI component within subsequent releases)

Logical Case Flow

The diagram below is intended to depict a logical view of the case steps for a typical case.

  1. A UI or other service calls the Case interface to create a Case instance
  2. The case instance is created & database data inserted
  3. A lifecycle event is raised indicating a case activity (created) event
  4. The case business rules capture the event and decide on an action to take
  5. Additionally other parties can subscribe to Case events via EDN
  6. The business rules may handle the event, e.g. configured to execute a case activity on case creation event
  7. The BPM/Human Workflow/Custom activity is executed
  8. A case activity event is raised on the execute activity
  9. A case work UI or business service can inspect the case instance and call other actions to progress that case, such as:
    • Execute activity
    • Add Note
    • Add document
    • Add case data
    • Update Milestone
    • Raise user defined event
    • Suspend case
    • Resume case
    • Close Case


Having had a little time to play around with the APIs and the case configuration, I really like the flexibility and power of combining Oracle Business Rules and the BPM Case Management event model. Creating something this flexible and powerful without BPM Case Management would take a lot of time and effort. This is hopefully going to save my customers a lot of time and effort!

I may make amendments to this post as my understanding of Case Management increases!

Take a look at the following links for official documentation etc.

Saturday May 04, 2013


Welcome to my blog!

Hi, and welcome to my blog. I am very lucky to have a day job that enables me to understand a whole range of Oracle middleware technology products and provide solutions to a variety of issues.  Some of these solutions have been obvious, some have involved pushing and prodding Oracle products or searching the lesser known areas of documentation to come to a conclusion.

I will be sharing some of these product solutions in the hope that it is going to be of use to someone out there!



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