OUD 12cPS4 Use Case: Oracle Database Name Services

Oracle Unified Directory (OUD) is one directory service product included in the Oracle Directory Services Plus (ODS+) suite that is used for a wide variety of use cases requiring LDAPv3 interoperability.  

One very common use case is Oracle Database name resolution. Oracle name resolution is referred to by several names including "net services", Transparent Network Substrate (TNS), and Oracle Names (ONAMES) depending on the Oracle Database version.

Oracle Database name resolution is to Oracle Databases as Domain Name Services (DNS) is to resolving a fully qualified domain name to an IP address to enable a web browser or ssh client to connect to the associated IP address.  For more information on Oracle Database name resolution (a.k.a. Net Services), see the Oracle Database documentation here: https://docs.oracle.com/en/database/oracle/oracle-database/19/netag/

Basic Workflow

In this use case, Oracle Database clients connect anonymously [default] or via basic authentication to the OUD directory server over either the LDAP [default] or LDAPS protocol.  Once connected to OUD, the database client requests the client connect string for a specific database.  The connect string is returned to the database client and then the database client uses the provided connection string to connect to the Oracle Database.  The following is a sample connect string returned by OUD:

(DESCRIPTION =
  (ADDRESS=(PROTOCOL=TCP)(HOST=node1.example.com)(PORT=1521))
  (CONNECT_DATA=(SERVICE_NAME=node1.example.com))
)

Once the database client has the connect string, it uses the information in the connect string to connect to the Oracle Database.

OUD Setup

The following is the basic workflow for setting up a pair of OUD instances for this use case on the same server:

1. Make the directory where the software will be installed

$ sudo mkdir /opt/oud/bits
$ sudo chown -R opc:opc /opt/oud

2. Download JDK and OUD into /opt/oud/bits

• JDK is available at https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
• Download the latest Linux x64 gz version, which is currently jdk-8u381-linux-x64.tar.gz
• OUD is available from eDelivery at https://edelivery.oracle.com/
• Login and search for Oracle Directory Services Plus 12.2.1.4.0
• Download V983402-01.zip
• Patches
• OPatch: https://updates.oracle.com/download/28186730.html (p28186730_139427_Generic.zip)
• OUD: https://updates.oracle.com/download/35263333.html (p35263333_122140_Generic.zip)

3. Extract the JDK and OUD software and patches

$ tar --directory=/opt/oud -zxf /opt/oud/bits/jdk-8u*-linux-x64.tar.gz
$ mv /opt/oud/jdk1.8.0* /opt/oud/jdk
$ unzip -d /opt/oud/bits/. /opt/ods/poc/bits/V983402-01.zip
$ unzip -d /opt/oud/bits/. /opt/ods/poc/bits/p28186730_139427_Generic.zip
$ unzip -d /opt/oud/bits/. /opt/ods/poc/bits/p35263333_122140_Generic.zip

4. Create input files for OUD installation and Oracle inventory

OUD installation response file (/opt/oud/bits/oud12c-standalone.rsp):

[ENGINE]
Response File Version=1.0.0.0.0
[GENERIC]
DECLINE_AUTO_UPDATES=true
MOS_USERNAME=
MOS_PASSWORD=
AUTO_UPDATES_LOCATION=
SOFTWARE_UPDATES_PROXY_SERVER=
SOFTWARE_UPDATES_PROXY_PORT=
SOFTWARE_UPDATES_PROXY_USER=
SOFTWARE_UPDATES_PROXY_PASSWORD=
ORACLE_HOME=/opt/oud/mw_oud12c
INSTALL_TYPE=Standalone Oracle Unified Directory Server (Managed independently of WebLogic server)

Oracle inventory file (/opt/oud/bits/oraInventory.loc)

inventory_loc=/opt/oud/oraInventory
inst_group=opc

Temporary password file for setup (/opt/oud/bits/.pw)

$ echo 'Oracle123' > /opt/oud/bits/.pw

Java security configuration file (/opt/oud/bits/tns-java.security) that allows anonymous cipher suites, which are required for registering databases with dbca

jdk.disabled.namedCurves = secp112r1, secp112r2, secp128r1, secp128r2, \
    secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, secp224k1, \
    secp224r1, secp256k1, sect113r1, sect113r2, sect131r1, sect131r2, \
    sect163k1, sect163r1, sect163r2, sect193r1, sect193r2, sect233k1, \
    sect233r1, sect239k1, sect283k1, sect283r1, sect409k1, sect409r1, \
    sect571k1, sect571r1, X9.62 c2tnb191v1, X9.62 c2tnb191v2, \
    X9.62 c2tnb191v3, X9.62 c2tnb239v1, X9.62 c2tnb239v2, X9.62 c2tnb239v3, \
    X9.62 c2tnb359v1, X9.62 c2tnb431r1, X9.62 prime192v2, X9.62 prime192v3, \
    X9.62 prime239v1, X9.62 prime239v2, X9.62 prime239v3, brainpoolP256r1, \
    brainpoolP320r1, brainpoolP384r1, brainpoolP512r1

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, NULL, \
    include jdk.disabled.namedCurves

jdk.tls.legacyAlgorithms= \
    K_NULL, C_NULL, M_NULL, \
    DH_anon, ECDH_anon, \
    RC4_128, RC4_40, DES_CBC, DES40_CBC, \
    3DES_EDE_CBC

5. Install the OUD software

$ export JAVA_HOME=/opt/oud/jdk
$ $JAVA_HOME/bin/java -d64 -jar /opt/oud/bits/fmw_12.2.1.4.0_oud.jar -silent -ignoreSysPrereqs -responseFile /opt/oud/bits/oud12c-standalone.rsp -invPtrLoc /opt/oud/bits/oraInventory.loc

6. Patch OUD to current bundle patch level

Set ORACLE_HOME environment variable

$ export ORACLE_HOME=/opt/oud/mw_oud12c

List patch inventory to see current OUD version and what patches are installed

$ $ORACLE_HOME/OPatch/opatch lsinventory

Install the OPatch patch

$ cd /opt/oud/bits/6880880
$ $JAVA_HOME/bin/java -jar /opt/oud/bits/6880880/opatch_generic.jar -silent oracle_home=$ORACLE_HOME

Install OUD patch responding interactively with y to both questions

cd /opt/oud/bits/35263333
$ $ORACLE_HOME/OPatch/opatch apply

List patch inventory to see compare with previous lsinventory output

$ $ORACLE_HOME/OPatch/opatch lsinventory

7. Set OPENDS_JAVA_ARGS environment variable so that when OUD instances start, they will use our custom tns-java.security configuration file rather than the default configuration file

$ export OPENDS_JAVA_ARGS="-Djava.security.properties=/opt/oud/bits/tns-java.security"

Note: Whenever you restart an OUD instance, you will want to set the OPENDS_JAVA_ARGS environment variable before starting the OUD instance.

8. Setup the first OUD instance

$ /opt/oud/mw_oud12c/oud/oud-setup --cli --integration eus --instancePath /opt/oud/mw_oud12c/oud1/OUD --adminConnectorPort 1444 --ldapPort 1389 --ldapsPort 1636 --httpAdminConnectorPort disabled --httpPort disabled --httpsPort disabled --baseDN dc=world --rootUserDN 'cn=Directory Manager' --rootUserPasswordFile /opt/oud/bits/.pw --addBaseEntry --generateSelfSignedCertificate --hostName $(hostname -f) --noPropertiesFile --no-prompt

9. Setup the second OUD instance

$ /opt/oud/mw_oud12c/oud/oud-setup --cli --integration eus --instancePath /opt/oud/mw_oud12c/oud2/OUD --adminConnectorPort 2444 --ldapPort 2389 --ldapsPort 2636 --httpAdminConnectorPort disabled --httpPort disabled --httpsPort disabled --baseDN dc=world --rootUserDN 'cn=Directory Manager' --rootUserPasswordFile /opt/oud/bits/.pw --addBaseEntry --generateSelfSignedCertificate --hostName $(hostname -f) --noPropertiesFile --no-prompt

10. Enable and initialize replication from OUD1 to OUD2

$ /opt/oud/mw_oud12c/oud2/OUD/bin/dsreplication enable --host1 $(hostname -f) --port1 1444 --bindDN1 'cn=Directory Manager' --bindPasswordFile1 /opt/oud/bits/.pw --replicationPort1 1989 --secureReplication1 --host2 $(hostname -f) --port2 2444 --bindDN2 'cn=Directory Manager' --bindPasswordFile2 /opt/oud/bits/.pw --replicationPort2 2989 --secureReplication2 --baseDN dc=world --adminUID admin --adminPasswordFile /opt/oud/bits/.pw --trustAll --no-prompt

11. Confirm that replication is working properly

$ /opt/oud/mw_oud12c/oud1/OUD/bin/dsreplication status --hostname $(hostname -f) --port 1444 --dataToDisplay compact-view --adminUID admin --adminPasswordFile /opt/oud/bits/.pw --advanced --trustAll --no-prompt

12. Configure OUD1 and OUD2 for TNS

Create /opt/oud/bits/tns.batch configuration file with the following content

set-connection-handler-prop --handler-name "LDAPS Connection Handler" --add ssl-cipher-suite:TLS_DH_anon_WITH_AES_256_GCM_SHA384 --add ssl-cipher-suite:TLS_DH_anon_WITH_AES_128_GCM_SHA256

create-password-policy --type generic --policy-name TNSAdmins --set password-attribute:userpassword --set default-password-storage-scheme:AES --set default-password-storage-scheme:Salted\ SHA-512

set-password-policy-prop --policy-name "Default Password Policy" --add default-password-storage-scheme:"EUS PBKDF2 SHA-512"

set-log-publisher-prop --publisher-name "File-Based Access Logger" --set enabled:true

Apply the eus.batch configuration file to OUD1

$ /opt/oud/mw_oud12c/oud1/OUD/bin/dsconfig -h $(hostname -f) -p 1444 -D 'cn=Directory Manager' -j /opt/oud/bits/.pw --batchFilePath /opt/oud/bits/tns.batch --no-prompt

Apply the eus.batch configuration file to OUD2

$ /opt/oud/mw_oud12c/oud1/OUD/bin/dsconfig -h $(hostname -f) -p 2444 -D 'cn=Directory Manager' -j /opt/oud/bits/.pw --batchFilePath /opt/oud/bits/tns.batch --no-prompt

Set OPENDS_JAVA_ARGS to use custom java.security and then restart OUD instances to apply cryptographic changes

$ export OPENDS_JAVA_ARGS="-Djava.security.properties=/opt/oud/bits/tns-java.security" 

Stop OUD1 and OUD2

$ /opt/oud/mw_oud12c/oud1/OUD/bin/stop-ds
$ /opt/oud/mw_oud12c/oud2/OUD/bin/stop-ds

Start OUD1 and OUD2

$ /opt/oud/mw_oud12c/oud1/OUD/bin/start-ds
$ /opt/oud/mw_oud12c/oud2/OUD/bin/start-ds

13. Create realm configuration to add TNS admin and grant privileges to manage database entries.  Here is a sample realm configuration file in LDIF format

dn: ou=TNSAdmins,cn=OracleContext
changetype: add
objectClass: top
objectClass: organizationalUnit
ou: TNSAdmins

dn: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext
changetype: add
objectClass: top
objectClass: organizationalperson
objectClass: inetorgperson
uid: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext
cn: tnsadmin
sn: TNS
givenName: Admin
userPassword: Oracle123
ds-privilege-name: password-reset
ds-privilege-name: unindexed-search
ds-privilege-name: modify-acl
ds-pwp-password-policy-dn: cn=TNSAdmins,cn=Password Policies,cn=config

dn: cn=Common,cn=Products,cn=OracleContext
changetype: modify
replace: orclSubscriberSearchBase
orclSubscriberSearchBase: dc=world

dn: cn=Common,cn=Products,cn=OracleContext
changetype: modify
replace: orclSubscriberNickNameAttribute
orclSubscriberNickNameAttribute: dc

dn: cn=Common,cn=Products,cn=OracleContext
changetype: modify
replace: orclDefaultSubscriber
orclDefaultSubscriber: dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonUserSearchBase
orclCommonUserSearchBase: ou=People,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonUserCreateBase
orclCommonUserCreateBase: ou=People,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonDefaultUserCreateBase
orclCommonDefaultUserCreateBase: ou=People,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonGroupCreateBase
orclCommonGroupCreateBase: ou=Groups,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonDefaultGroupCreateBase
orclCommonDefaultGroupCreateBase: ou=Groups,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonGroupSearchBase
orclCommonGroupSearchBase: ou=Groups,dc=world

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonNicknameAttribute
orclCommonNicknameAttribute: uid

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonKrbPrincipalAttribute
orclCommonKrbPrincipalAttribute: userPrincipalName

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonNamingAttribute
orclCommonNamingAttribute: cn

dn: cn=Common,cn=Products,cn=OracleContext,dc=world
changetype: modify
replace: orclCommonWindowsPrincipalAttribute
orclCommonWindowsPrincipalAttribute: samAccountName

dn: cn=OracleContextAdmins,cn=groups,cn=OracleContext,dc=world
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleDomainAdmins,cn=OracleDefaultDomain,cn=OracleDBSecurity,cn=Products,cn=OracleContext,dc=world
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=PolicyCreators,cn=Policies,cn=LabelSecurity,cn=Products,cn=OracleContext,dc=world
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleDBCreators,cn=OracleContext
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleNetAdmins,cn=OracleContext
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleContextAdmins,cn=Groups,cn=OracleContext
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleUserSecurityAdmins,cn=Groups,cn=OracleContext
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleNetAdmins,cn=OracleContext,dc=world
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

dn: cn=OracleDBCreators,cn=OracleContext,dc=world
changetype: modify
add: uniqueMember
uniqueMember: cn=tnsadmin,ou=TNSAdmins,cn=oracleContext

14. Apply the realm configuration changes with ldapmodify

$ /opt/oud/mw_oud12c/oud/bin/ldapmodify -h $(hostname -f) -Z -X -p 1636 -D 'cn=Directory Manager' -j /opt/oud/bits/.pw -c -f /opt/oud/bits/tns.realm

Configure Database

1. Configure an Oracle database to register it into OUD by updating sqlnet.ora and adding ldap.ora

Sample sqlnet.ora illustrating the insertion of LDAP into the NAMES.DIRECTORY_PATH variable

NAMES.DIRECTORY_PATH= (LDAP,TNSNAMES, EZCONNECT)

Sample ldap.ora

DIRECTORY_SERVERS= (ol8.example.com:1389:1636,ol8.example.com:2389:2636)
DEFAULT_ADMIN_CONTEXT = "dc=world"
DIRECTORY_SERVER_TYPE = OID

2. Register Oracle database

Set Oracle database environment

$ export ORACLE_HOME=/opt/ods/poc/db/19c/dbhome_1
$ export ORACLE_BASE=/opt/ods/poc/db/19c/app/oracle
$ export TNS_ADMIN=/opt/ods/poc/db/19c/dbhome_1/network/admin
$ export ORACLE_SID=ol8

Register CDB database

$ /opt/ods/poc/db/19c/dbhome_1/bin/dbca -silent -configureDatabase -sourceDB $ORACLE_SID -registerWithDirService true -dirServiceUserName cn=tnsadmin,ou=TNSAdmins,cn=oracleContext -dirServicePassword Oracle123 -walletPassword Oracle123

Register PDB database

$ $ORACLE_HOME/bin/dbca -silent -configurePluggableDatabase -pdbName PDB1 -sourceDB $ORACLE_SID -registerWithDirService true -dirServiceUserName cn=tnsadmin,ou=TNSAdmins,cn=oracleContext -dirServicePassword Oracle123 -walletPassword Oracle123

3. Confirm registration with tnslookup

Lookup container database (CDB)

$ $ORACLE_HOME/bin/tnsping $ORACLE_SID

Lookup pluggable database (PDB)

$ $ORACLE_HOME/bin/tnsping PDB1_$ORACLE_SID

List all registered databases

$ /opt/oud/mw_oud12c/oud/bin/ldapsearch -T -h $(hostname -f) -p 1636 -X -Z -D cn=tnsadmin,ou=TNSAdmins,cn=oracleContext -j /opt/oud/bits/.pw -b dc=world -s sub '(|(objectClass=orclDBServer)(objectClass=orclNetService))'

I hope that you found this helpful!

Blessings!

Brad