New OUD Source Code plugin examples

I’ve just published a couple of OUD plugin examples to help customers develop their own extensions.

The ZIP package includes 2 plugin examples to demonstrate the richness of OUD plugin API. The FilterDistributor can be used to route bind request to 2 different workflow elements based on a condition present on the user entry about to be used for authentication. The PasswordSchemeUpgrade  can be used to migrate passwords from one storage/encryption scheme to another.

Plugins examples are available at http://www.oracle.com/technetwork/middleware/id-mgmt/learnmore/oid-demos-182820.html

OUD Plugin API reference is available at http://docs.oracle.com/cd/E49437_01/apirefs.111220/e38583/index.html

OUD Plugin Developer Guide is available at http://docs.oracle.com/cd/E49437_01/doc.111220/e38455/toc.htm

Advertisements

How to get OUD to start on Linux/UNIX boot

To simplify integration of OUD with the target OS, you can use the create-rc-script command  to generate a shell script to start, stop, and restart the directory server. You can update the resulting script to suit the needs of your directory service. This command is available for UNIX or Linux systems.

So you can use this command to create RC scripts e.g. run  sudo create-rc-script -f /etc/init.d/oud -u oud.

Then run this script when the appropriate run level change on the target distribution. For instance, on OEL, run sudo chkconfig –level 3 oud on

Make sure you use the -u userName option unless you really want to run OUD as root.

Using OUD with Oracle Directory Integration Platform (DIP)

This post will guide you through configuring OUD as a DIP backend instead of OID.
Such deployment is supported since DIP 11.1.1.7.0  (PS6).

1- Install OUD and configure 1 suffix to be synchronized, e.g. dc=example,dc=com

HOST=beagle
PORT=1389
SPORT=1636
APORT=4444
ADMIN="cn=Directory Manager"
PASSWD=welcome1
PW_FILE=/tmp/pwd
echo $PASSWD > "$PW_FILE"
oud-setup --cli --hostName "$HOST" --ldapPort $PORT --ldapsPort $SPORT --adminConnectorPort 4444 --rootUserDN "$ADMIN" --rootUserPasswordFile "$PW_FILE" --generateSelfSignedCertificate --enableStartTLS --baseDN dc=example,dc=com --addBaseEntry --ldifFile /home/sylvain/lib/ldif/Example.ldif --no-prompt --noPropertiesFile

2- Configure a suffix holding DIP configuration

DIP stores its configuration in cn=Products,cn=oracleContext.
You must create and initialize a local backend holding the cn=oracleContext suffix with the commands below:

dsconfig create-workflow-element --set base-dn:cn=oraclecontext --set enabled:true --type db-local-backend --element-name myNewDb --hostname $HOST --port $APORT --bindDN "$ADMIN" --bindPasswordFile "$PW_FILE" --trustAll --no-prompt
 
dsconfig create-workflow  --set base-dn:cn=oraclecontext  --set enabled:true  --set workflow-element:myNewDb  --type generic  --workflow-name workFlowForMyNewDb  --hostname "$HOST"  --port $APORT --bindDN "$ADMIN" --bindPasswordFile "$PW_FILE" --trustAll  --no-prompt
dsconfig set-network-group-prop  --group-name network-group --add workflow:workFlowForMyNewDb --hostname $HOST --port $APORT --bindDN "$ADMIN" --bindPasswordFile "$PW_FILE" --trustAll --no-prompt

then create top entry and Products entry:

ldapmodify -a -p $PORT -h $HOST -D "$ADMIN" -w "$PASSWD" <<EOF
dn: cn=oraclecontext
objectClass: top
objectClass: container
dn: cn=Products,cn=oraclecontext
objectClass: top
objectClass: container
EOF

3- Enable changelogs

DIP stores its configuration in cn=Products,cn=oracleContext.OUD uses OUD changelogs for both data anc configuration to detect changes efficiently.

dsreplication enable-changelog --no-prompt --baseDN "dc=example,dc=com" --hostname "$HOST" --port $APORT --bindDN "$ADMIN" --adminPasswordFile "$PW_FILE" --trustAll

dsreplication enable-changelog --no-prompt --baseDN "cn=Products,cn=oraclecontext" --hostname "$HOST" --port $APORT --bindDN "$ADMIN" --adminPasswordFile "$PW_FILE" --trustAll

4- Grant access to synchronized data

ldapmodify -h localhost -p 1389 -D "$ADMIN" -w "$PASSWD" <<EOF
dn: dc=example,dc=com
changetype: modify
add: aci
aci: (target="ldap:///dc=example,dc=com")(version 3.0; acl "Entry-level DIP permissions"; allow (all,proxy) groupdn="ldap:///cn=dipadmingrp,cn=DIPadmins,cn=Directory Integration Platform,cn=Products,cn=oraclecontext"; allow (all,proxy) groupdn="ldap:///cn=odipigroup,cn=DIPadmins,cn=Directory Integration Platform,cn=Products,cn=oraclecontext"; )
-
add: aci
aci: (targetattr="*")(version 3.0; acl "Attribute-level DIP permissions"; allow (all,proxy) groupdn="ldap:///cn=dipadmingrp,cn=DIPadmins,cn=Directory Integration Platform,cn=Products,cn=oraclecontext"; allow (all,proxy) groupdn="ldap:///cn=odipigroup,cn=DIPadmins,cn=Directory Integration Platform,cn=Products,cn=oraclecontext";)
EOF

Note: Make sure to enable LDAPS port (LDAP over SSL) if you plan to synchronize userPassword with DIP as this is required for obvious security reasons.

5 – Install DIP

The procedure is described in http://docs.oracle.com/cd/E23943_01/install.1111/e12002/oud.htm#CHDEDHBG Make sure to Install DIP only (do not run the Configure procedure as it is OID specific)

Data Adaptation again

Yet another common usage of OUD Transformations to transparently adapt some values during provisioning:

In this real use case, ODIP (Oracle Directory Integration Platform) is used to synchronize some SQL tables with OUD.
The country every user is living in is stored in an Oracle DB and is synchronized by DIP into the LDAP country attribute.
Unfortunatelly, the country name format expected by the applications on the Directory side differ from the one used on the DB side.

In this case, country name is stored in full in the DB (e.g. USA, FRANCE, ITALY) when apps that contact OUD expect standard country short form e.g. US, FR, IT.  For administrative and political reasons within the enterprise, it is not possible to create a additional mapping table in the RDBMS that could be used by a SQL JOIN to return the correct values.

OUD Tranformation Framework can be used to address that integration problem: a so-called add inbound tranformation is invoked when a new entry is created and value mapping is applied on the incoming add request before it is processed by the OUD database engine. For sake of peformance, this transformation can be configured to trigger on udates originated from DIP only, using the network group mechanism.

To create a transformation that maps USA to US and France to FR, do the following:

First create the transformation with the appropriate mappings:

dsconfig create-transformation \
–set source-attribute:country=%country%(US,USA)(FR,France)(IT,Italy) \
–type add-inbound-attribute \
–transformation-name mapCountry \
–set conflict-behavior:virtual-overrides-real 

Then stash this transformation to a Transformation Workflow element to be inserted ahead of local DB (userRoot):

dsconfig create-workflow-element \
–set enabled:true \
–set next-workflow-element:userRoot \
–set transformation:mapCountry \
–type transformations \
–element-name mapCountry

Then put the Transformation Workflow Element to the appropriate workflow so  that it can be invoked:

dsconfig set-workflow-prop \
–workflow-name userRoot1 \
–set workflow-element:mapCountry

At that stage, appropriate values are automatically stored in OUD.

OUD External change log and rootDSE search

Some LDAP client applications perform subtree searches with search base set to the rootDSE (empty DN).
Oracle Unified Directory (OUD) nicely routes the search to every top level suffix automatically.

When the replication is enabled, OUD automatically publicizes all changes that have occurred in a directory server database in the cn=changelog suffix. This is particularly useful for synchronizing the LDAP directory with other subsystems.  The cn=changelog suffix may contains millions of changes depending on the modification rate on the replication topology and the change retention policy (purge delay).

Subtree searches with search base set to the rootDSE are routed to the cn=changelog suffix as well as long as the replication is enabled. In general, this is not a problem in testing/stagging area, because the changelog is almost empty. However, in production, this may have big impact on performances as this suffix may contain many entries. Furthermore, custom  indexes corresponding to client access pattern do not exist on that suffix, so they can’t be used to speed up entry processing.

In order to address that problem, you can disable the so-called external changelog, without disabling the underlying replication changelog used by the replication. To do so, run the following command on the OUD servers for each user suffixes:

dsconfig -h <hostname> -p <admin port>  -D “cn=directory manager” -w <admin password> -n \
set-external-changelog-domain-prop \
–provider-name “Multimaster Synchronization” –domain-name <your suffix>  \
–set enabled:false

Note: some provisoning apps may require the external changelog to synchronize with external systems. If so, keep the external changelog enabled on a couple of OUD servers and reserve them for these apps.