While there are many great articles available online for installing and setting up Oracle Identity Management (OIM) with Active Directory (AD) integration, one topic many posts fail to cover is the map file which tells OIM how to handle records from AD. The fact that many AD installations are far from LDAP-compliant only serves to compound frustrations with setting up Single Sign-On (SSO). This post covers a few of my findings from a recent encounter with the elusive SSO trophy.
Map Files: A Brief Introduction
After you’ve installed OIM and setup your connection to AD in the dipassistant, you will find map files which are usually stored in $ORACLE_HOME/ldap/odi/conf with names based on the AD connection name. There are two map files; one is for importing from AD and one is for exporting to AD. These map files, along with a configuration file, make up what is called a “profile” that is used by the oidctl process to import, export and sync LDAP records.
The import map file has at least three primary uses: loading records into OIM directly from AD using an LDAP connection, loading records into OIM from an AD ldif export and loading records from one ldif file to another ldif file. The bulkload tool has been provided by Oracle at least since OIM was known as OID (Oracle Internet Directory). The dipassistant bootstrap process is a newer tool. Bootstrapping is Oracle’s term for loading records and is performed with the dipassistant. Both bulkloader and bootstrapping can use the import map file to manipulate an AD export ldif. Bootstrapping has the benefit of importing records directly from an LDAP source. However, bulkloader is much faster and can handle significantly more records.
The following is a sample import map file with all the comments trimmed out. The map file has two sections: DomainRules and AttributeRules. Most AD installations are managed in such a way that users are not always in the users container (CN=USERS). The DomainRules section takes care of mapping organizational units (OU) into the users container. The sample map files shows how the AD was setup to reflect an organizational structure rather than an LDAP structure by placing departments under the domain rather than under users. In order to import all of AD users, the map file will need to address all of the organizational units and groups of users not directly in the users container.
The AttributeRules section of the import map file is a bit less complicated but, by default, has extra information that your OIM install may not require. The mapping of the uid attribute is usually the most important since it is the attribute users will authenticate with. Your installation may prefer to login with the AD sAMAccountName (aka username or userid) or with the AD email address found in the mail attribute. While the attribute used by OIM for authentication can be set, the default is uid. In addition to determining the authentication attribute, the AttributeRules section also maps the AD fields to fields which can be used for searching the OIM. This is important if you plan to use your OIM installation as a company directory or user lookup tool. The sample provided below contains minimal mapping since the installation serves primarily as an SSO authentication service.
DomainRules CN=USERS,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Information Services,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Distribution,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Contractors,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Southern Division,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Sealines,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Human Resources,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Accounting,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Hourly Employees,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: ou=Eurocom,DC=MyCompany,DC=com:CN=USERS,DC=MyCompany,DC=com: AttributeRules objectguid: :binary: :orclobjectguid: : :bin2b64(objectguid) ObjectSID: :binary: :orclObjectSID: : :bin2b64(ObjectSID) ou: : :organizationalunit:ou: : organizationalunit cn: : :container: cn: :orclContainer dc: : :domain: dc: :domain sAMAccountName,userPrincipalName: : :user:orclSAMAccountName: :orclADUser:toupper(truncl(userPrincipalName,'@'))+"$"+sAMAccountname sAMAccountName: : :user:orclUserPrincipalName: :orclADUser:userPrincipalName sAMAccountName: : :user:uid: :inetorgperson sAMAccountName: : :user:krbPrincipalName: :orcluserv2:trunc(userPrincipalName,'@')+'@'+toupper(truncl(userPrincipalName,'@')) cn: : :user:sn: : person cn: : :person:cn: :person givenName: : :person:displayName: :orcluserV2 mail: : :user:mail: :inetorgperson mobile: : :organizationalperson:mobile: :inetorgperson cn: : :group:cn: :groupofuniquenames Description: : :group:Description: :orclgroup member: : :group:uniquemember: :groupofUniqueNames managedby: : :group:owner: :orclprivilegegroup
Putting The Map To Work
There are several ways to import records from AD into OIM. Three of the most common are bulkloading from an ldif file, bootstrapping from an ldif file and bootstrapping from an LDAP directory. The process I used bootstraps an AD export ldif file into an ldif file which I then bulkload into OIM. The extra step of going from ldif to ldif not only applies the mapping rules, but also allows for the review of records before importing into OIM.
The following are my steps for success:
- Initial setup of OAS 10.1.2.0.2
- Patch to version 10.1.4.3.0
- Setup AD Configuration in dipassistant -gui
- Edit map file
- Enable import profile using dipassistant
- bootstrap ldif to ldif
The ldif-to-ldif command (Step 6.) is as follows:
dipassistant bootstrap -cfg=/u01/oracle/infra/10.2/ldap/odi/samples/ldf2ldf.properties
The ldf2ldf.properties file contains the mapping, source and destination information used by the bootstrap process. The contents of my ldf2ldf.properties file are as follows.
#source type odip.bootstrap.srctype = LDIF #source file odip.bootstrap.srcurl = /home/oracle/exportUser.ldif #destination type odip.bootstrap.desttype = LDIF #destination file odip.bootstrap.desturl = /home/oracle/importUser.ldif #map file to use odip.bootstrap.mapfile = /home/oracle/adImport.map #logfile location odip.bootstrap.logfile = /u01/oracle/sso1/ldap/odi/log/bootstrap.log #log level odip.bootstrap.logseverity = 15 #trace file location odip.bootstrap.trcfile = /u01/oracle/sso1/ldap/odi/log/bootstrap.trc
The importUser.ldif file should contain entries such as the following which reflect the application of the AttributeRules specified in the import map file:
dn: cn=Mark Fennell,cn=users,dc=mycompany,dc=com cn: Mark Fennell orclSAMAccountName: MYCOMPANY.COM$MarkFennell orclUserPrincipalName: Mark.Fennell@mycompany.com uid: MarkFennell krbPrincipalName: Mark.Fennell@mycompany.com sn: Mark Fennell displayName: Mark mail: Mark.Fennell@mycompany.com objectclass: orclcontainer objectclass: orcladuser objectclass: inetorgperson objectclass: orcluserv2 objectclass: person objectclass: groupofuniquenames
The bulkload command (Step 7.) is as follows:
bulkload.sh -connect orcl -generate -load -check /home/oracle/importUsers.ldif
The bulkload process will list the log files it generates. Once you have a successful bulkload, you can use the oidadmin tool or the self-service web portal to verify entries in the OIM LDAP directory. The self-service portal is usually located at a url similar to http://sso1.mycompany.com:7777/oiddas/.
Finally, the opmnctl startall and oidctl start commands should be issued to begin the synchronization process which can be monitored in the aud and trc files located in $ORACLE_HOME/ldap/odi/log.
oidctl connect=orcl host=sso1.mycompany.com server=ODISRV instance=2 configset=1 flags=”debug=63″ start
The oidctl command is used to start and stop the ODISRV service that manages the synchronization of LDAP records between OIM and AD. The debug=63 flag provides comprehensive debugging information.
dipassistant bootstrap -cfg=/u01/oracle/sso1/ldap/odi/samples/ldf2ldf.properties
Bootstrapping with a config file applies the mapping rules of the import map file to an ldif file and writes the results to either an ldif file or an LDAP destination. This process is used to create an ldif file from an AD export that can be used to bulkload or bootstrap records into OIM.
bulkload.sh -connect orcl -generate -load -check ~/importUsers.ldif
Located in the $ORACLE_HOME/ldap/bin directory, the bulkload tool loads records from an ldif file into OIM. If you have more than 200 records, bulkload is faster than bootstrapping.
dipassistant bootstrap -h sso1.mycompany.com -p 389 -profile adImport
An alternative to the bulkload tool, bootstrapping allows you to go import directly from one LDAP source into OIM. If you only have a few hundred records, this is easier than processing an ldif file and then bulkloading.
ldapsearch -h orcyssoweb1 -p 389 -d “cn=orcladmin” -b “cn=Users,dc=mycompany,dc=com” “(objectclass=orcluserv2)” “cn=*” > /home/oracle/users.ldif
ldapdelete -h orcyssoweb1 -p 389 -D “cn=orcladmin” -w oracle11g -c -v -f /home/oracle/users.ldif
Use the ldapdelete command with caution. Sometimes you need to start over with your loading. These two commands, ldapsearch and ldapdelete, allow you to create an ldif file that can be used to delete all of your users. Beware however, that you will need to edit the ldif file and remove the orcladmin and public users as well as any other critical users.
dipassistant modifyprofile -h orcyssoweb1 -p 389 -D cn=orcladmin -w p@ssword -profile ad_connectorImport odip.profile.configfile=$ORACLE_HOME/ldap/odi/conf/adImport.cfg
The dipassistant modifyprofile option allows you to enable and disable profiles as well as make changes to the config file. The only parameter I changed is the SkipErrorToSyncNextChange parameter, which allows you to continue processing synchronization in the event that a single record fails to synchronize. If you set this parameter to true, you should monitor the aud and trc files in $ORACLE_HOME/ldap/odi/log.