Introduction

If you have been using Oracle’s Identity Management software for at least the last few years you will probably be familiar or at least heard of OVD (Oracle Virtual Directory), which was originally acquired back in 2005 from a company called OctetString. OVD provides a vast number of great virtual features used to aggregate multiple backend data stores and present LDAP consumers a single unified Directory Server. Beginning with OUD version 11.1.2.1.0, there have been a number of virtualization features added similar to what is provided in OVD. This trend has continued through OUD 11.1.2.3.0 where features such as joining multiple backends was added.

The OUD Transformation Framework can do various things as presented in the latest documentation “Understanding the Transformation Framework”, but in order to help illustrate how this feature can really add value I recently worked with a customer where leveraging a Transformation Rule helped solved a problem. Because the existing documentation is either confusing or lacking, I decided to write this article to help learn more about the Transformation Framework and how to make it work. An important note I want to alert you is at the time this article was published in order to use the OUD virtualization features you are required to have what is called a “Oracle Directory Service Plus” license http://www.oracle.com/us/products/middleware/identity-management/oracle-directory-services/overview/index.html. If you have any questions about that please refer to your local Oracle Sales Representative.

My Example Data Transformation Use Case

Some times the best way to help explain something is to tell a story that relates to the problem. So to help illustrate I am building a use case that will leverage the Transformation Framework to solve a problem. In actuality my use case is based on some work I did with a real customer, but I am modifying some of the details in order to protect any confidential details of the solution.

Let’s say Acme Company is using the Oracle Unified Directory (OUD) and has millions of users. Each user in the OUD Directory store has an attribute named “st” for State (This is specifically a inetOrgPerson attribute profile for USA, but you can extrapolate and change it to something that seems more related to what you are planning.), and each user is assigned a single value. For example if you are from California, your LDAP profile will have the attribute “st” with the abbreviated state value “CA”, Florida you will have st=FL, and so on. Now Acme Company is also using Oracle Access Manager (OAM) to authenticate each user and in the authentication process gets an incoming value that identifies what state each user is from, but the problem in lies the incoming value is the real name and not the abbreviated value. For example Adina authenticates, she is from Florida and the value passed to OAM is Florida, not FL. Acme Company wants to leverage the incoming value during authentication to look her up in OUD so that they can personalize her experience, but unfortunately the incoming value “Florida” does not match what is in the OUD Directory “FL”.

How OUD Transformation Framework will solve the Problem

We know the incoming value will always be consistent, so all we need to do is use that value to map it to the appropriate attribute and value in the OUD Directory Server. Refer to the following sequence diagram in order to illustrate how the OUD Proxy Transformation Framework will solve the authentication process from OAM to OUD Proxy to OUD Directory.

Notice in the flow that the OUD Proxy it gets a LDAP filter request from OAM in the form of “virtST=Florida” and the OUD Proxy Transformation Rule changes it to “st=FL” so that the lookup will be found and Adina will correctly be identified to below to Florida. By the way, the attribute “virtST” does not exist in the OUD Directory, it only exists in the OUD Proxy; more on that later. Hopefully at this point you can begin to brainstorm how this feature could apply to your Identity application. What I am about to cover gives the basics on how to implement the Transformation Framework, but it should also give you the basics that could be applied to other OUD virtual features.

How to Create a OUD Proxy Data Transformation

An important aspect to working with the Transformation Framework is understanding the component dependencies. Below is a diagram to help illustrate those dependencies.

As the diagram illustrates, the first component #1 to be created will be the custom schema (Note if you follow the command line option, creating the attribute is not required though I will mention it is recommended.), then #2 create a Transformation Rule, and so forth.

There are a couple approaches to creating the Transformation Rule. Option 1) is using the Command-line, and option 2) is using the GUI in ODSM (Oracle Directory Service Manager). I am going to show both approaches because there are pros and cons to both and leave it up to you to pick which option works best in your situation.

Command-line Approach to Create the Transformation

First things first, all instructions going forward are done in the OUD Proxy Server, NOT OUD Directory Server. This is a very important point to remember.

To stage all the commands that are going to be executed, I am listing all the associated parameter names and values; please associate the values in the commands and adjust for your environment as needed. In addition, I am also color-coding all associated values between steps to help clearly illustrate how certain components relate to each other as pointed out in the previous OUD Proxy Transformation Dependencies diagram.

OUD Proxy Hostname:       localhost

OUD Proxy Instance Port:  2389

OUD Proxy Admin Port:     2444

OUD Super User Name:      cn=Directory Manager

OUD Super User Password:  passwd.txt(password inside file)

OUD Base DN to Invoke WF: cn=users,dc=oracle,dc=com

Step 1 – Change to the OUD Proxy Instance bin directory

All command line actions will be run from the OUD Proxy Instance bin directory. It is important to know this is the bin directory in the OUD Proxy instance and not the OUD Directory Server instance, so change to the bin directory in the OUD Proxy Instance.

cd <OUD Proxy Instance>/OUD/bin

Step 2 – Create a custom schema attribute

Let’s create a custom attribute, which by the way is only extended to the OUD Proxy, and is not created in the OUD Directory. So there is no worry about making any changes in the main OUD Directory Server data store.

If you only use the command-line option the custom attribute is not really required. However, I highly recommend creating the custom attribute because if you decide to modify the Transformation Rule in any way, when saving the changes it will complain the “Client attribute” does not exist and saving any changes will simply fail. Therefore I highly recommend creating the custom attribute.

The following custom attribute definition should be placed in some file; e.g. customAttribute.ldif. Keep in mind the following example is for my use case, your attribute will most likely be completely different. Please refer to the OUD Administration Documentation on creating custom attributes in the OUD Proxy Server.

Example File customAttribute.ldif -
-----------------------------------------------------------
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( 2.5.4.8.101
NAME ( 'virtST' )
DESC 'Virtual transformation attribute'
SUP name EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
X-ORIGIN 'RFC 4519'
USAGE userApplications )

Run command –
-----------------------------------------------------------
./ldapmodify \
-h localhost \
-p 2389
-D cn=Directory\ Manager \
-j passwd.txt \
-a -f customAttribute.ldif

Example Output –
-----------------------------------------------------------
Processing MODIFY request for cn=schema
MODIFY operation successful for DN cn=schema

Step 3 – Create Outbound Attribute Addition Transformation

The following will create the Outbound Attribute Transformation Rule. In my example below I only included 3 of the 50 states for the sake of illustration, but you can extrapolate for your use case and make necessary adjustments. Notice the association between the attribute “virtST” created in the previous step is associated in the following command; shown in bold red.

./dsconfig \
-h localhost \
-p 2444 \
-D cn=Directory\ Manager \
-j passwd.txt \
-n create-transformation \
--type add-outbound-attribute \
--set client-attribute:virtST=%st%\(Florida,FL\)\(Minnesota,MN\)\(Wisconsin,WI\) \
--transformation-name virtState

Step 4 – Create Transformation Workflow Element

The following creates a Transformation Workflow Element and associates the Transformation rule “virtState” created in the previous state; shown in bold blue.

./dsconfig \
-h localhost \
-p 2444 \
-D cn=Directory\ Manager \
-j passwd.txt \
-n create-workflow-element \
--set enabled:true \
--set next-workflow-element:load-bal-we1 \
--set transformation:virtState \
--type transformations \
--element-name workflow-elem-state

Step 5 – Create Workflow

The following command creates the required Workflow and associates the Workflow Element “workflow-elem-state” created from the previous step; shown in bold green.

./dsconfig \
-h localhost \
-p 2444 \
-D cn=Directory\ Manager \
-j passwd.txt \
-n create-workflow \
--set base-dn:cn=users,dc=oracle,dc=com \
--set enabled:true \
--type generic \
--set workflow-element:workflow-elem-state \
--workflow-name workflow-state

Step 6 – Set Workflow to Network Group

The final command does not actually create anything, but instead associates the Workflow “workflow-state” created in the previous step to the main network group; shown in bold brown.

./dsconfig \
-h localhost \
-p 2444 \
-D cn=Directory\ Manager \
-j passwd.txt \
-n set-network-group-prop \
--group-name network-group \
--add workflow:workflow-state

TIP: In the previous step part of the command to create the Workflow had a parameter “--set base-dn:”, which defined the namespace to which the Transformation will be invoked; in my example it was cn=users,dc=oracle,dc=com. If you open ODSM and log into the OUD Proxy, go to the Configuration tab, expand Network Groups, and finally select network-group, you will see the associated workflows. If there are any workflows that already has been defined with the same base DN, you will get an error as follows:

The Network Group could not be modified because of the following reason:

* [LDAP: error code 53 - Entry cn=network-group,cn=Network
Groups,cn=config cannot be modified because one of the configuration
change listeners registered for that entry rejected the change: Unable
to register the workflow because the base DN 'cn=users,dc=oracle,dc=com'
is already registered with the network group 'network-group']

The reason for this is because the network group can only have unique base DNs for each associated workflow. If you get this error you will need to go into ODSM and review the network group in the Proxy Server to see which base DNs are related to all the workflows attached to the network group.

If you do not intend to create the Transformation using ODSM, you can skip to the end where you test the Transformation rule out.

ODSM Approach to Create the Transformation

The following shows all the required steps to accomplish everything done using the command-line in ODSM.

Step 1 – Login to ODSM

Open ODSM (Oracle Directory Service Manager) and login as an administrator to the OUD Proxy Server instance.

Step 2 – Create a custom schema attribute

NOTE: The following attribute creation is based on my example and not yours, so modify accordingly. Navigate to the Schema tab and create a new attribute by finding the existing attribute “st” and then clone it. Enter a new name “virtST” and a OID value <your OID value>. Be sure the OID value is unique and does not conflict with any existing schema attributes or any future LDAP RFC schema attributes. Finally click Apply to create the attribute.

Step 3 – Create Outbound Attribute Addition Transformation

Navigate to the Configuration tab > click on the CORE Configuration icon > right click on Transformation > select Create Outbound Attribute Addition Transformation.

Enter “virtState” in the Name field and click the Define… button > select Value of Another Attribute > enter or select “st” (This attribute in OUD the transformation will be mapped to) > and finally click the Create button.

Name: virtST
Attribute: st
Value Mapping:

On Matching	Replace With
FL	Florida
MN	Minnesota
WI	Wisconsin

IMAGE6

Step 4 – Create Transformation Workflow Element

In the CORE Configuration area icon right click on Workflow Elements > select Create Transformation Workflow Element > enter the following and click the Create button.

Name: workflow-elem-state
Next Workflow Element: load-bal-we1
Transformations: select “virtState”