Before You Begin

This tutorial shows you how to create and configure a Union workflow element with Union Partitions for Oracle Unified Directory (OUD) 12c.

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

Background

The Union Workflow Element (WFE) provides functionality allowing you to aggregate several DITs into a virtual unified DIT. You can customize bind and search routing policies, assigning priorities to specific partitions. An example would be an LDAP bind operation that can be satisified by multiple partitions. The Union WFE allows you to prioritize partitions so that the bind request is routed to the partition with the highest priority. A search policy might be configured so that a search continues to the next partition only when a result is not returned by the higher priority partition.

What Do You Need?

• A basic understanding of Linux
• An environment with at least 16 GB of physical memory, Oracle Enterprise Linux 6.6 or later, and oracle and root credentials
• Two OUD 12c LDAP Server instances and a single OUD Proxy Server running on oud.example.com. The following assumptions are made for this OBE:
• The first standalone OUD instance, unionA, is running on LDAP port 1389 and LDAP administration port 4444
• The second standalone OUD instance, unionB, is running on LDAP port 2389 and LDAP administration port 2444
• The Proxy OUD instance, unionP, is running on LDAP port 3389 and LDAP administration port 3444
• The unionpartA.ldif file is loaded to the unionA OUD instance
• The unionpartB.ldif file is loaded to the unionB OUD instance
• This tutorial assumes the following directory locations:
  
  • ORACLE_BASE=/u01/app/oracle
  • OUD_ORACLE_HOME=/u01/app/oracle/product/oud/oud
  • OUD_INSTANCES=/u01/app/oracle/config/oud_instances

Configure OUD Directory Server Instances

To deploy a Union workflow element configuration, you first need to set up two OUD Directory Server instances, unionA and unionB.

1. Navigate to the $OUD_ORACLE_HOME directory.
2. Run the oud-setup command to create the first OUD instance, unionA.

   ./oud-setup \
   --cli \
   --no-prompt \
   --hostname oud.example.com \
   --ldapPort 1389 \
   --adminConnectorPort 1444 \
   --baseDN dc=exampleA,dc=com \
   --ldifFile ~/unionpartA.ldif \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPasswordFile ~/pwd.txt \
   --instancePath /u01/app/oracle/config/oud_instances/unionA \
   --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/unionA
   .....Done.
   See /u01/app/oracle/config/oud_instances/unionA/logs/oud-setup for a
   detailed log of this operation.
   
   Configuring Directory Server ..... Done.
   Creating Base Entry dc=exampleA,dc=com ..... Done.
   Starting Directory Server ....... Done.
   
   To see basic server configuration status and configuration you can launch
   /u01/app/oracle/config/oud_instances/unionA/bin/status
   

3. Run the oud-setup command to create the second OUD instance, unionB:

   ./oud-setup \
   --cli \
   --no-prompt \
   --hostname oud.example.com \
   --ldapPort 2389 \
   --adminConnectorPort 2444 \
   --baseDN dc=exampleB,dc=com \
   --ldifFile ~/unionpartB.ldif \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPasswordFile ~/pwd.txt \
   --instancePath /u01/app/oracle/config/oud_instances/unionB \
   --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/unionB
   .....Done.
   See /u01/app/oracle/config/oud_instances/unionB/logs/oud-setup for a
   detailed log of this operation.
   
   Configuring Directory Server ..... Done.
   Creating Base Entry dc=exampleB,dc=com ..... Done.
   Starting Directory Server ....... Done.
   
   To see basic server configuration status and configuration you can launch
   /u01/app/oracle/config/oud_instances/unionB/bin/status
   

Configure the OUD Proxy Server

Create the OUD proxy server unionP and configure it to support the Union WFE configuration.

1. Navigate to the $OUD_ORACLE_HOME directory.
2. Run the oud-proxy-setup command to create a proxy server instance, unionP, as follows:

   ./oud-proxy-setup \
   --cli \
   --no-prompt \
   --hostname oud.example.com \
   --ldapPort 3389 \
   --adminConnectorPort 3444 \
   --rootUserDN "cn=Directory Manager" \
   --rootUserPasswordFile ~/pwd.txt \
   --instancePath /u01/app/oracle/config/oud_instances/unionP \
   --noPropertiesFile

   The output should look similar to this:

   Successfully wrote the updated Directory Server configuration
   Starting the Server :
   /u01/app/oracle/config/oud_instances/unionP/bin/start-ds --timeout 0 
   [28/Nov/2019:06:18:25 -0800] category=CORE severity=INFORMATION msgID=132 msg=The Directory Server is beginning the configuration bootstrapping process
   ...
   ...
   org.opends.server.DirectoryServerStarted, alert ID 458887):  The Directory Server has started successfully

3. Navigate to the $OUD_ORACLE_HOME/bin directory.
4. Create an LDAP Server Extension, LDAPExtunionA that provides details of the host and port required to connect to unionA.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-extension \
   --set enabled:true \
   --type ldap-server \
   --extension-name LDAPExtunionA \
   --set remote-ldap-server-address:oud.example.com \
   --set remote-ldap-server-port:1389

5. Create an LDAP Proxy workflow element, ProxyLDAPWFEunionA, that sets the bind mode for unionA.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-workflow-element \
   --set enabled:true \
   --type proxy-ldap \
   --element-name ProxyLDAPWFEunionA \
   --set ldap-server-extension:LDAPExtunionA \
   --set client-cred-mode:use-client-identity

6. Create an LDAP Server Extension, LDAPExtunionB that provides details of the host and port required to connect to unionB.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-extension \
   --set enabled:true \
   --type ldap-server \
   --extension-name LDAPExtunionB \
   --set remote-ldap-server-address:oud.example.com \
   --set remote-ldap-server-port:2389

7. Create an LDAP Proxy workflow element, ProxyLDAPWFEunionB, that sets the bind mode for unionB.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-workflow-element \
   --set enabled:true \
   --type proxy-ldap \
   --element-name ProxyLDAPWFEunionB \
   --set ldap-server-extension:LDAPExtunionB \
   --set client-cred-mode:use-client-identity

8. Run the dsconfig command to view the server extensions.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   list-extensions

   The output should look similar to this:

   Extension                      : Type
   -------------------------------:-------------------------------
   Directory Integration Platform : directory-integration-platform
   LDAPExtunionA                  : ldap-server
   LDAPExtunionB                  : ldap-server
   REST Server                    : rest-server
   REST Web Services Provider     : rest-web-service

9. Run the dsconfig command to view the proxy LDAP workflow elements.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   list-workflow-elements

   The output should look similar to this:

   Workflow Element   : Type               : enabled
   -------------------:--------------------:--------
   adminRoot          : ldif-local-backend : true
   ProxyLDAPWFEunionA : proxy-ldap         : true
   ProxyLDAPWFEunionB : proxy-ldap         : true
   virtualAcis        : db-local-backend   : true

Create the Union Workflow Element

1. Create a new Union Workflow element unionwfe by running the dsconfig command:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-workflow-element \
   --set base-dn:dc=example,dc=com \
   --set enabled:true \
   --type union \
   --element-name unionwfe

Configure the Union Workflow

Configure the Union Workflow unionwf by running the dsconfig command:

1. Create a workflow unionwf to associate the Union workflow element unionfwe with the base DN.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-workflow \
   --set base-dn:dc=example,dc=com \
   --set enabled:true \
   --set workflow-element:unionwfe \
   --type generic \
   --workflow-name unionwf

2. Attach the workflow unionwf to the default network group.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-network-group-prop \
   --group-name network-group \
   --set workflow:unionwf

Create Union Partitions for the OUD Server Instances

Create two new Union Partitions for the OUD instances (unionA and unionB) by running the dsconfig command:

1. Create a new Union Partition unionpartA for the OUD instance unionA.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-union-partition \
   --element-name unionwfe \
   --set workflow-element:ProxyLDAPWFEunionA \
   --type generic \
   --partition-name unionpartA \
   --set priority:1 \
   --set source-base-dn:ou=people,dc=exampleA,dc=com \
   --set relative-base-dn:ou=people

2. Create a new Union Partition unionpartB for the OUD instance unionB.

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   create-union-partition \
   --element-name unionwfe \
   --set workflow-element:ProxyLDAPWFEunionB \
   --type generic \
   --partition-name unionpartB \
   --set priority:2 \
   --set source-base-dn:ou=people,dc=exampleB,dc=com \
   --set relative-base-dn:ou=people

Validate Union Workflow Element Configuration : SEARCH

In this step you will run the ldapsearch command to return data from the Union Workflow. You will set partition priorities and WFE properties to various values to see what effect they have on the entries and values returned. To view the current setting for the WFE properties you can run the following dsconfig command at any time:

1. Run the dsconfig command to show the current settings of the WFE properties:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   get-workflow-element-prop --element-name unionwfe

   The properties should be set to the values shown here:

   Property                  : Value(s)
   --------------------------:--------------------
   auto-tune-search-option   : false
   base-dn                   : "dc=example,dc=com"
   bind-option               : bind-first-success
   cache-size                : 10000
   enabled                   : true
   search-first-match        : true
   suppress-entry-duplicates : false

2. You will search for using the filter cn=Rock.

   The source entry for OUD instance unionA is:

   dn: cn=Rock,ou=People,dc=exampleA,dc=com
   objectClass: top
   objectClass: inetorgperson
   cn: Rock
   sn: Anne
   givenname: Anne rock
   telephonenumber: 54300
   userpassword: {SSHA512}k3OOowAeqVKYocFLX2Ct3qYF0SZx8e+Xyn//r+hm2h0o/YhhhukaxJGlv
    L1mY4tIATV+enHIhnggDMew6n4lkQFC4TJrII4U

   The source entry for OUD instance unionB is:

   dn: cn=Rock,ou=People,dc=exampleB,dc=com
   objectClass: top
   objectClass: inetorgperson
   cn: Rock
   sn: Anne
   title: Manager
   telephonenumber: 99999
   userpassword: {SSHA512}k3OOowAeqVKYocFLX2Ct3qYF0SZx8e+Xyn//r+hm2h0o/YhhhukaxJGlv
    L1mY4tIATV+enHIhnggDMew6n4lkQFC4TJrII4U
   

3. Run the ldapsearch command via the OUD Proxy unionP using the filter cn=Rock:

   ./ldapsearch \
   --hostname oud.example.com \
   --port 3389 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --baseDN "dc=example,dc=com" -s sub "(cn=Rock)"

   You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com
   sn: Anne
   cn: Rock
   userPassword: {SSHA512}k3OOowAeqVKYocFLX2Ct3qYF0SZx8e+Xyn//r+hm2h0o/YhhhukaxJGlv
    L1mY4tIATV+enHIhnggDMew6n4lkQFC4TJrII4U
   objectClass: top
   objectClass: inetorgperson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: 54300
   givenName: Anne rock

   Note: The entry returned is from unionA:
   
   • The entry/entries from the partition with the highest priorityare returned i.e. unionpartA:priority=1
   • Duplicate entries matching the filter cn=Rock are not returned i.e. search-first-match=true
4. Change the priority of the partition unionA so that it is lower priority than unionB using the dsconfig command:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-union-partition-prop \
   --element-name unionwfe \
   --partition-name unionpartA \
   --set priority:10

5. Run the ldapsearch command via the OUD Proxy unionP using the filter cn=Rock:

   ./ldapsearch \
   --hostname oud.example.com \
   --port 3389 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --baseDN "dc=example,dc=com" -s sub "(cn=Rock)"

   You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com
   sn: Anne
   title: Manager
   cn: Rock
   userPassword: {SSHA512}c/O7Ue63CBw3UAHd5QFPPDSuQyWyyh2bipVMG88nfuEQAFGJm+fCvbdfv
    1tmzrnyhDO921LIXR6+Hc2HDUAFCzUcHgJv2wI9
   objectClass: top
   objectClass: inetorgperson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: 99999

   Note: The entry returned is from unionB:
   
   • The entry/entries from the partition with the highest priorityare returned i.e. unionpartB:priority=2
   • Duplicate entries matching the filter cn=Rock are not returned i.e. search-first-match=true
   Set the priority of the unionA partition back to 1:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-union-partition-prop \
   --element-name unionwfe \
   --partition-name unionpartA \
   --set priority:1

6. Change the value of the search-first-match property to 'false' using the dsconfig command:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-workflow-element-prop \
   --element-name unionwfe \
   --set search-first-match:false

7. Run the ldapsearch command via the OUD Proxy unionP using the filter cn=Rock:

   ./ldapsearch \
   --hostname oud.example.com \
   --port 3389 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --baseDN "dc=example,dc=com" -s sub "(cn=Rock)"

   You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com
   sn: Anne
   cn: Rock
   userPassword: {SSHA512}wHTCdfEuR2e+41i/BITbhxUn4dUR6TGSWEcFdQVzFeiYiP2enDM7+v4dy
    PBp1It/EdFNKCKJw4hGHVOzDaDc55Zxxv2paKTy
   objectClass: top
   objectClass: inetorgperson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: 54300
   givenName: Anne rock
   
   dn: cn=Rock,ou=people,dc=example,dc=com
   sn: Anne
   title: Manager
   cn: Rock
   userPassword: {SSHA512}c/O7Ue63CBw3UAHd5QFPPDSuQyWyyh2bipVMG88nfuEQAFGJm+fCvbdfv
    1tmzrnyhDO921LIXR6+Hc2HDUAFCzUcHgJv2wI9
   objectClass: top
   objectClass: inetorgperson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: 99999

   Note: The entries from both partitions are returned:
   
   • Duplicate entries from both partitions matching the filter cn=Rock are returned i.e. search-first-match=false
8. Change the value of the suppress-entry-duplicates property to 'true'using the dsconfig command:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-workflow-element-prop \
   --element-name unionwfe \
   --set suppress-entry-duplicates:true

   Run the ldapsearch command again. You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com
   sn: Anne
   cn: Rock
   userPassword: {SSHA512}wHTCdfEuR2e+41i/BITbhxUn4dUR6TGSWEcFdQVzFeiYiP2enDM7+v4dy
    PBp1It/EdFNKCKJw4hGHVOzDaDc55Zxxv2paKTy
   objectClass: top
   objectClass: inetorgperson
   objectClass: organizationalPerson
   objectClass: person
   telephoneNumber: 54300
   givenName: Anne rock

   Note: The entry from the unionA partition is returned:
   
   • Duplicate entries are suppressed i.e. suppress-entry-duplicates=true

Validate Union Workflow Element Configuration : BIND

In this step you will run the ldapsearch command to bind as a user. You will set WFE properties to various values to see what effect they have on the user's ability to bind to the OUD instances.

1. Issue a search for DNs binding as the user cn=Rock,ou=People,dc=exampleA,dc=com:

   ./ldapsearch \
   --hostname oud.example.com \
   --port 3389 \
   --bindDN "cn=Rock,ou=people,dc=example,dc=com" \
   -w WelcomeA \
   --baseDN "ou=people,dc=example,dc=com" \
   -s sub "(cn=Rock)" dn

   You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com

2. Issue a search for DNs binding as the user cn=Rock,ou=People,dc=exampleB,dc=com:

   ./ldapsearch \
   --hostname oud.example.com \
   --port 3389 \
   --bindDN "cn=Rock,ou=people,dc=example,dc=com" \
   -w WelcomeB \
   --baseDN "ou=people,dc=example,dc=com" \
   -s sub "(cn=Rock)" dn

   You should see the following output:

   dn: cn=Rock,ou=people,dc=example,dc=com

   Note: You can bind as the cn=Rock user in both partitions. This is indicated by using the different passwords for each user in the respective partitions i.e. unionA is 'WelcomeA' while unionB is 'WelcomeB'.

3. Change the value of the bind-option property to 'bind-quick-fail'using the dsconfig command:

   ./dsconfig \
   --hostname oud.example.com \
   --port 3444 \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile ~/pwd.txt \
   --trustAll \
   --no-prompt \
   set-workflow-element-prop \
   --element-name unionwfe \
   --set bind-option:bind-quick-fail

4. Issue the ldapsearch commands from Steps 1 and 2 in this section again.

   In both cases ou should see the following output:

   Result Code:  49 (Invalid Credentials)
   Additional Information:  The bind operation failed due to duplicate bind DN cn=Rock,ou=people,dc=example,dc=com

   The bind fails as you have duplicate users in the partitions.

Want to Learn More?

• Understanding Union Workflow Element
• Configuring a Union Workflow Element Deployment with Union Partition

Feedback

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