UCM Integration with OES (Business Cases)

Introduction

Following up with the postings about extending UCM’s security model with OES, I decided to create this post to complete the picture about how to actually configure the policies in OES to protect UCM resources in a scalable fashion. The initial posts cover how to modify and configure the JavaAPIExample-with-custom-classloader Java SSM to integrate OES to UCM via a custom component developed as a filter in UCM. That on its own is tremendously valuable, however, once that is accomplished, how can we take advantage of it?
Customers have a large variety of requirements suiting their particular business needs when it comes to managing corporate content. UCM provides a great deal of flexibility for companies to store, categorize and manage their documents and content in general. OES has also a lot of flexibility when providing sophisticated security schemes to control access to that content. However, if we are not careful making the right decisions, the actual solution may not live up to the task at hand and may be more disappointing than anything else.

OES certainly supports protecting URL’s like for Web Applications. UCM can potentially represent content via URL’s, however, representing all document URL’s as OES resources would be impractical to say the least, and totally unmanageable for large amounts of content, which is definitely the case for big corporations.
Recently, I had the opportunity to reassemble the OES-UCM integration for a POC in EMEA. During the engagement, I realized that most customers, not only in that region but pretty much in general, use Accounts in UCM. One specific requirement of this POC was to be able to simplify how the relationships between documents are accounts are maintained without having to touch every single document. So the intent here is to describe a potential solution to this problem which could be recommended to customers and doesn’t necessarily represent what real customers currently have in place.

Overview

First of all, let’s do a quick overview of the integration’s architecture to have an initial picture of what we have at our disposal to tackle this problem.
For starters, on the UCM side a custom component implementing UCM’s filter interfaces is required to tie OES into UCM’s hooks for custom integrations. Part of this component would be an OES API Wrapper object that will provide the UCM components with a mechanism to call out to OES when the events invoking the custom component are triggered. The following diagram shows the basic architecture of the integration:

Fig. 1 – Basic Integration Architecture UCM-OES.

As described in previous posts the configuration of the java-ssm instance part of the integration as shown above is embedded into UCM via the intradoc.cfg configuration file. So the flow is basically like follows:

1. User logs in to UCM and it is authenticated by UCM providers.

2. User starts navigating through UCM accessing content (check-out, check in, undo check-out, check in similar, document information, etc).

3. UCM generates events from the user’s activity and invokes the subscribed components for each triggered event.

4. The ucmoes component is invoked and it processes the event extracting all the metadata for the document along with the security context of the user trying to access the content. All this is transferred to OES via the OESAPIWrapperImpl object part of the ucmoes component implementation.

5. OES asserts the identity of the user, extracts all attributes that need to be retrieved if any, evaluates policies (role policies, authorization policies) according to how things are configured in OES server, and determines if the user is allowed or not access to the requested resource.

There’s nothing really fancy up to this point, right? Now let’s pay closer attention to some other aspects that are also part of the functionality offered by OES which can be very useful to UCM.

Attribute Retrievers

One of the most powerful capabilities of OES is the fact that OES can virtually extract information from anywhere. This is possible using attribute retrievers. OES comes packed with out of the box attribute retrievers for the most common repository types (LDAP, DBMS) and if that is not enough, you can easily create your own custom attribute retriever.
The attribute retrievers are specially useful for the purposes of dynamic business logic evaluation impacting authorization decisions.

Evaluation Functions

The concept of evaluation functions is also very powerful. Basically, evaluation functions can be used to extract the contents of attributes coming from the request made from UCM into OES (in this case all the content’s associated metadata) and perform custom evaluation of that data to determine a true or false response, which in turn can be used in role mapping and/or authorization policies. The format in which parameters are passed to evaluation functions is very flexible; pretty much there are no restrictions on the number of arguments passed to the evaluation function as long as the evaluation function’s code knows how to deal with the values being passed in.
For our purposes, evaluation functions are a key piece of the puzzle, and you’ll know why soon.

Requirements and Solutions

Here comes the fun part. According to the requirements expressed by some customers, the use of accounts to control access to content is very common. I can see why using accounts provides a lot of flexibility within UCM to increase the granularity of the security model enforced on top of content. The key point here is to maintain the Account’s Hierarchy fairly stable and unchanged. Now UCM ties users to accounts giving permissions to users over the accounts. This restricts even further what users can do with certain content despite the privileges assigned to the security group controlling access to the content. Accounts supersede the permissions granted by Security Groups which means only the privileges granted by both the Account and the Security Group will be made part of the user’s privileges. This may sound a little confusing but it is actually very simple. In other words, the intersection of the two sets of permissions (Account and Security Group) is what permissions the user will ultimately have.
UCM has all the facilities to configure these relationships, so what value is added by OES? Well, OES can enrich the semantics of what it actually means to be part of the account and with what privileges. UCM has just direct assignment of users into HRDocAdmin account and with specific permissions. OES on the other hand can actually say: “The user is a member of the HRDocAdmin account if he belongs to the HR Director’s department and has the title ‘HR Auditor’ but only until March 2011”. The way OES policies are specified allow for a more comprehensive analysis of the user’s attributes along with present circumstances external to the user’s profile to determine if a user is part of the account and with what privileges. In other words, OES makes it possible to express the relationship between users and account in a more dynamic fashion.
Going back to the requirements, I am going to present a possible solution to the requirements of using a hierarchy of accounts to protect content and use OES as the engine to determine user access to accounts and therefore to their respective protected resources.

For starters, I will say it is fine to associate accounts with resources but once a resource is associated to an account this bond should never change anymore. Accounts should be fixed and the privileges of users over those accounts can change, even over time; and the policies that determine that are specified in OES.

At the beginning of this article I mentioned two OES features that will help a great deal in the implementation of a solution to these requirements, Attribute Retrievers and Evaluation Functions. These elements available in OES will allow us to define policies beyond simple direct assignment of user permissions over accounts, which is available directly from UCM.

Here is the scenario:

A company is divided in 6 organizations based on location:

• North West Organization
• North East Organization
• North Central Organization
• South West Organization
• South East Organization
• South Central Organization

A set of states belongs to each Organization. Each state has its own set of content items in UCM. Only people from a given state with Author or ContentAdmin roles can modify the documents that belong to that state. Other Authors/ContentAdmins in other States within the same Organization still have read access to those documents. So in other words everyone within an organization has access to the account that belongs to that organization, but the permissions over the content vary based on the state that generated the document. Needless to say, People in other organizations don’t have access to documents that don’t belong to their organization because they will have no access over the corresponding accounts. If we wanted to take this even further, we could easily design a scheme of exceptions for inter-organization access to content generated by different organizations. As a matter of fact, if the content is labeled public in an attribute called xDocExceptionStatus part of the metadata associated to the content item; then everyone has access to that document regardless of the account privileges.

To be able to implement this scenario in OES we need to have access to a few pieces of information: the Organization that created the document, the Organization that a person belongs to, the state where this person’s office is located and the dExceptionStatus of the content item to determine if the item is public or not. The attributes associated to people are retrieved using attribute retrievers that are connected to the repository where those attributes are stored. For the attributes associated to the content we will use evaluation functions, which have access to request time attributes passed as part of the context associated to the authorization request.

For the purposes of our example, all attributes describing employees are stored in LDAP, therefore, the out of the box LDAP Attribute Retriever will do. Now, the next part of the solution is custom developed, we will create an evaluation function that will determine if the user has proper permissions over a content item based on his/her organization and his/her content role.

The code listing below shows the implementation of the evaluation function that tests the value of the document’s metadata attributes against the user’s LDAP attributes.

package oes;
import java.util.Map;
import javax.security.auth.Subject;
import weblogic.security.spi.Resource;
import weblogic.security.service.ContextHandler;

import com.bea.security.providers.authorization.asi.ARME.evaluator.RequestHandle;

public class UCMOESEvaluationFunction {
public UCMOESEvaluationFunction() {
super();
}

public boolean assertAttributes (RequestHandle requestHandle, Object[] args, Subject subject, Map roles, Resource resource, ContextHandler contextHandler) {
AttributeElement xDocExceptionStatus = requestHandle.getAttribute("xDocExceptionStatus",true);
AttributeElement xDocState = requestHandle.getAttribute("xDocState",true);
AttributeElement xDocOrg = requestHandle.getAttribute("xDocOrg",true);

String strXDocExceptionStatus = xDocExceptionStatus.getValueAs(String.class);
String strXDocState = xDocState.getValueAs(String.class);
String strXDocOrg = xDocOrg.getValueAs(String.class);

if (strXDocExceptionStatus.equalsIgnoreCase("public")) {
return true;
}
else {
try {
if (strXDocExceptionStatus.equalsIgnoreCase("restricted")) {
return args[0].toString().equalsIgnoreCase(strXDocOrg);
}
else {
return (args[0].toString().equalsIgnoreCase(strXDocState) &&
args[0].toString().equalsIgnoreCase(strXDocOrg));
}
}
catch (Exception e ) {
e.printStackTrace();
return false;
}
return false;
}

void init(Map config) {
}

void shutdown() {
}
}


All this function does is to extract the Attributes from the document’s metadata passed as properties from the client. It does that using the requestHandle parameter passed to the function method. Then compares the values with the ones passed as arguments to the function from the OES policy using this function. Within the policy OES passes the values of the dynamic attributes for st (State) and o (Organization) using the following constraint expression:

sys_defined(st) AND sys_defined(o) AND assertAttributes(st, o)

As shown by the expression above, only users that exist in LDAP having these attributes populated will be evaluated for access. The first two calls to sys_defined function prevent non-LDAP stored users from making it through to our evaluation function, so these users get rejected immediately. Part of the configuration would be having two dynamic attributes tied to the same LDAP attribute retriever.

By doing this we are adding a sophisticated access policy that would fit the business requirements for the accounts without the limitations from UCM policies based on simple group membership.

The deployment of the function above is described In Oracle Entitlements Server documentation and is out of scope for this document, so please refer to it if you want to try this approach.

Summary

OES can extend the security model of UCM so the semantics of access policies can be enriched to support more sophisticated authorization schemes.

The combination of Attribute Retrievers and Evaluation Functions is a very powerful mechanism to implement sophisticated access policies with very rich semantics and also a very dynamic nature if the users' data change overtime affecting their access to content stored in UCM.

This is just a sample implementation of potential requirements. It is not intended to serve as the basis of a real implementation meant to be released in production.