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 port1389
and LDAP administration port4444
- The second standalone OUD instance,
unionB
, is running on LDAP port2389
and LDAP administration port2444
- The Proxy OUD instance,
unionP
, is running on LDAP port3389
and LDAP administration port3444
- 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
.
- Navigate to the
$OUD_ORACLE_HOME
directory. - 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
- 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.
- Navigate to the
$OUD_ORACLE_HOME
directory. - 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
- Navigate to the
$OUD_ORACLE_HOME/bin
directory. - Create an LDAP Server Extension,
LDAPExtunionA
that provides details of the host and port required to connect tounionA
../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
- Create an LDAP Proxy workflow element,
ProxyLDAPWFEunionA
, that sets the bind mode forunionA
../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
- Create an LDAP Server Extension,
LDAPExtunionB
that provides details of the host and port required to connect tounionB
../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
- Create an LDAP Proxy workflow element,
ProxyLDAPWFEunionB
, that sets the bind mode forunionB
../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
- 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
- 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
Create a new Union Workflow element
unionwfe
by running thedsconfig
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:
- Create a workflow
unionwf
to associate the Union workflow elementunionfwe
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
- 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:
- Create a new Union Partition
unionpartA
for the OUD instanceunionA
../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
- Create a new Union Partition
unionpartB
for the OUD instanceunionB
../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:
- 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
- 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
- Run the
ldapsearch
command via the OUD ProxyunionP
using the filtercn=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 fromunionA
:
- 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
- The entry/entries from the partition with the highest priorityare returned i.e.
- Change the priority of the partition
unionA
so that it is lower priority thanunionB
using thedsconfig
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
- Run the
ldapsearch
command via the OUD ProxyunionP
using the filtercn=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 fromunionB
:
- 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
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
- The entry/entries from the partition with the highest priorityare returned i.e.
- Change the value of the
search-first-match
property to 'false' using thedsconfig
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
- Run the
ldapsearch
command via the OUD ProxyunionP
using the filtercn=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
- Duplicate entries from both partitions matching the filter
- Change the value of the
suppress-entry-duplicates
property to 'true'using thedsconfig
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 theunionA
partition is returned:
- Duplicate entries are suppressed i.e.
suppress-entry-duplicates=true
- Duplicate entries are suppressed i.e.
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.
- 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
- 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' whileunionB
is 'WelcomeB'. - Change the value of the
bind-option
property to 'bind-quick-fail'using thedsconfig
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
- 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?
Feedback
To provide feedback on this tutorial, please contact Identity Management User Assistance.