Before You Begin

This tutorial shows you how to configure the Attribute Transformation Type in Oracle Unified Directory 12c (OUD). The Attribute Transformation Type provides functionality previously provided by the VirtualAttribute Plug-in of Oracle Virtual Directory 11g (OVD).

This tutorial is part of the Oracle Virtual Directory 11g to Oracle Unified Directory 12c Transition Series.

Background

The Attribute Transformation Type allows you to add, replace and remove attributes and their values. For example, a new application requires a person's full name to be used in their display. Rather than referring to the cn attribute, the application wants to use the displayname attribute, which does not exist in the source data. Using the Transformation Type, you can add a virtual attribute, displayname and assign the value of the cn attribute to it. The cn attribute remains available for other applications that are looking for it.

What Do You Need?

• An environment with at least 16 GB of physical memory, Oracle Enterprise Linux 6.6 or later
• A basic understanding of Linux
• Installation of Oracle Unified Directory 12c (12.2.1.3.0 or above)
• The virtualattr.ldif sample data file should be located in your $HOME directory for loading into the OUD instance you create as part of this tutorial.
• This tutorial assumes that you have already defined the following environment variables:
• OUD_ORACLE_HOME=/u01/app/oracle/product/oud/oud
• OUD_INSTANCES=/u01/app/oracle/config/oud_instances

Configure a Directory Server Instance

In this section, you'll use the oud-setup utility to set up an Oracle Unified Directory 12c server instance.

1. Navigate to the OUD_ORACLE_HOME directory, where the Oracle Unified Directory 12c software is installed. Run the oud-setup utility from the command line to setup an Oracle Unified Directory server instance.
   

   # ./oud-setup \
   --cli \
   --no-prompt \
   --hostname oud.example.com \
   --ldapPort 1389 \
   --adminConnectorPort 4444 \
   --baseDN dc=example,dc=com \
   --ldifFile ~/virtualattr.ldif \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPasswordFile ~/pwd.txt \
   --instancePath /u01/app/oracle/config/oud_instances/vattr \
   --noPropertiesFile

   The output should look similar to this:
   

   Oracle Unified Directory 12.2.1.4.0
   Please wait while the setup program initializes...
   
   Creating instance directory /u01/app/oracle/config/oud_instances/vattr
   .....Done.
   See /u01/app/oracle/config/oud_instances/vattr/logs/oud-setup for a
   detailed log of this operation.
   
   Configuring Directory Server ..... Done.
   Importing LDIF file /u01/app/home/oracle/virtualattr.ldif ....... Processed 8 entries, imported 8, skipped 0, rejected 0 and migrated 0 in 0
   seconds (average rate 11.9/sec)
   
   Starting Directory Server ....... Done.
   
   To see basic server configuration status and configuration you can launch
   /u01/app/oracle/config/oud_instances/vattr/bin/status
   

   Note : The ~/pwd.txt should contain the password that you want to assign to your OUD Administrator.

   Note : The virtualattr.ldif sample data should be loaded to this OUD instance.

Create Transformations to Add Virtual Attributes

In this step you use the dsconfig command to create Transformations that:

• Set the displayName attribute to the value from the cn attribute.
• Set the companyName attribute to the literal 'MyExampleCompany'

1. Navigate to the $OUD_ORACLE_HOME/bin directory and run the following dsconfig command to create the Transformation, displayName=%cn%.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-transformation \
   --set client-attribute:displayName=%cn% \
   --set conflict-behavior:merge-real-and-virtual \
   --type add-outbound-attribute \
   --transformation-name displayNameVA

2. Run the following dsconfig command to create the Transformation, companyName=MyExampleCompany.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-transformation \
   --set client-attribute:companyName=MyExampleCompany \
   --set conflict-behavior:merge-real-and-virtual \
   --type add-outbound-attribute \
   --transformation-name companyNameVA

Create Transformation Workflow Element

In this step you use the dsconfig command to create the Workflow Element for the Transformation, and assign the displayNameVA and companyNameVA transformations to the WFE.

1. Create the WFE using the dsconfig command and assign the displayNameVA transformation to the WFE.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-workflow-element \
   --set transformation:displayNameVA \
   --set next-workflow-element:userRoot \
   --type transformations \
   --set enabled:true \
   --element-name vattrwfe

2. Add the companyNameVA transformation to the WFE using the dsconfig command.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-workflow-element-prop \
   --element-name vattrwfe \
   --add transformation:companyNameVA

Validate the Replace Transformation

In this step you use the ldapsearch command to validate that the Replace tranformation you created is working correctly.

1. Run the ldapsearch command to validate the Replace Transformation.

   ./ldapsearch \
   --hostname oud.example.com \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --baseDN "dc=example,dc=com" \
   --searchScope sub \
   "objectclass=person"

2. Output should be similar to this. Note the following:

   
   
   • The giveName attribute is added and assigned the value of the sn attribute.

   dn: uid=exampleUser1uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser1
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: User1
   givenName: testUser
   description: This is the description for exampleUser1.
   companyName: Oracle
   uid: exampleUser1uid
   displayName: cnforexampleUser1
   
   dn: uid=exampleUser2uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser2
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: +1 390 103 6917
   givenName: User2
   givenName: testUser
   description: This is the description for exampleUser2.
   companyName: Oracle
   uid: exampleUser2uid
   displayName: cnforexampleUser2
   
   dn: uid=exampleUser3uid,ou=People,dc=example,dc=com
   sn: Hello
   cn: cnforexampleUser3
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: User3
   givenName: Hello
   description: This is the description for exampleUser3.
   companyName: Oracle
   uid: exampleUser3uid
   displayName: cnforexampleUser3

   Note that the givenName attribute has 2 values returned - the original value and the replaced value. This is due to the configuration setting conflict-behavior:merge-real-and-virtual. You can modify this configuration so that only the replaced value is displayed.

   
   
3. Run the dsconfig command to update the conflict-behavior configuration setting to the value virtual-overrides-real for the givenNameVA transformation.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-transformation-prop \
   --transformation-name givenNameVA \
   --set conflict-behavior:virtual-overrides-real

4. Rerun the search command. Output should be similar to this. Note the following:
   
   
   • The giveName attribute is assigned the value of the sn attribute. Only this value of the giveName attribute is returned.

   dn: uid=exampleUser1uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser1
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: testUser
   description: This is the description for exampleUser1.
   companyName: Oracle
   uid: exampleUser1uid
   displayName: cnforexampleUser1
   
   dn: uid=exampleUser2uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser2
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: +1 390 103 6917
   givenName: testUser
   description: This is the description for exampleUser2.
   companyName: Oracle
   uid: exampleUser2uid
   displayName: cnforexampleUser2
   
   dn: uid=exampleUser3uid,ou=People,dc=example,dc=com
   sn: Hello
   cn: cnforexampleUser3
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: Hello
   description: This is the description for exampleUser3.
   companyName: Oracle
   uid: exampleUser3uid
   displayName: cnforexampleUser3

Update the WFE with a Remove Transformation

In this step you add another tranformation to the Workflow Element to remove the description attribute.

1. Run the dsconfig command to create the transformation.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-transformation \
   --set source-attribute:description \
   --type filter-outbound-attribute \
   --transformation-name removedesc

2. Run the dsconfig command to add the transformation to the WFE.

   ./dsconfig \
   --hostname oud.example.com \
   --port 4444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-workflow-element-prop \
   --element-name vattrwfe \
   --add transformation:removedesc

3. Run the ldapsearch command to validate the Remove Transformation.

   ./ldapsearch \
   --hostname oud.example.com \
   --port 1389 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --baseDN "dc=example,dc=com" \
   --searchScope sub \
   "objectclass=person"

   Output should be similar to this. Note the following:

   
   
   • The description attribute has been removed and is not returned.

   dn: uid=exampleUser1uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser1
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: testUser
   companyName: Oracle
   uid: exampleUser1uid
   displayName: cnforexampleUser1
   
   dn: uid=exampleUser2uid,ou=People,dc=example,dc=com
   sn: testUser
   cn: cnforexampleUser2
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: +1 390 103 6917
   givenName: testUser
   companyName: Oracle
   uid: exampleUser2uid
   displayName: cnforexampleUser2
   
   dn: uid=exampleUser3uid,ou=People,dc=example,dc=com
   sn: Hello
   cn: cnforexampleUser3
   objectClass: top
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   givenName: Hello
   companyName: Oracle
   uid: exampleUser3uid
   displayName: cnforexampleUser3

Want to Learn More?

• Understanding the Transformation Framework
• Configuring Transformation Using dsconfig

Feedback

To provide feedback on this tutorial, please contact Identity Management User Assistance.