6 Configuring Directory Synchronization

Distinguished Name Mapping

This section specifies how entries are mapped between Oracle Internet Directory and a connected directory. If the mapping is between Oracle Internet Directory and another LDAP directory, then you can create multiple mapping rules. The domain rule specifications appear after a line containing only the keyword DomainRules. Each domain rule is represented with the components, separated by colons, and are described in Table 6-2.

Distinguished Name Rules
%USERBASE INSOURCE%:%USERBASE ATDEST%:

USERBASE refers to the container from which the third-party directory users and groups must be mapped. Usually, this is the users container under the root of the third-party directory domain.

Distinguished Name Rules
cn=users,dc=us,dc=mycompany,dc=com:cn=users,dc=us,dc=mycompany,dc=com 

cn=groups,dc=us,dc=mycompany,dc=com:cn=groups,cn=users,dc=us,dc=mycompany,dc=com

DomainExclusionList
OU=myou,OU=test,DC=mycompany,DC=com
OU=mynewou,OU=test,DC=mycompany,DC=com

Attribute-Level Mapping

The attribute rule specifications appear after a line containing only the keyword AttributeRules. Attribute rules specify how property values for an entry are related between two LDAP directories. For example, the cn attribute of a user object in one directory can be mapped to the givenname object in another directory. Similarly, the cn attribute of a group object in one directory can be mapped to the displayname attribute in another directory. Each attribute rule is represented with the components, separated by colons, and are described in Table 6-3. The attribute rule specifications end with a line three number signs (###).

To enter mapping rules in a synchronization profile, edit a file that strictly follows the correct format.

AttributeExclusionList
facsimileTelephoneNumber
telephonenumber

DomainRules
ou=rfi6894748, DC=imtest, DC=com : ou=rfi6894748, cn=users, dc=us, dc=oracle, dc=com:
DomainExclusionList
OU=myou,OU=rfi6894748,DC=imtest,DC=com
OU=mynewou,OU=rfi6894748,DC=imtest,DC=com
###
AttributeRules
# attribute rule common to all objects
objectguid: :binary: :orclobjectguid:string: :bin2b64(objectguid)
ObjectSID: :binary: :orclObjectSID:string:orclADObject:bin2b64(ObjectSID)
distinguishedName: : : :orclSourceObjectDN: :orclADObject
# USER ENTRY MAPPING RULES
# attribute rule for mapping windows LOGIN id
sAMAccountName,userPrincipalName: : :user:orclSAMAccountName: :orclADUser:toupper(truncl(userPrincipalName,'@'))+"$"+sAMAccountname
# attribute rule for mapping Active Directory LOGIN id
userPrincipalName: : :user:orclUserPrincipalName: :orclADUser:userPrincipalName
# Map the userprincipalname to the nickname attr by default
userPrincipalName: : :user:uid: :inetorgperson:userPrincipalName
# Map the SamAccountName to the nickname attr if required
# If this rule is enabled, userprincipalname rule needs to be disabled
#sAMAccountName: : :user:uid: :inetorgperson
# Assign the userprincipalname to Kerberaos principalname
userPrincipalName: : :user:krbPrincipalName: :orcluserv2:trunc(userPrincipalName,'@')+'@'+toupper(truncl(userPrincipalName,'@'))
# This rule is mapped as SAMAccountName is a mandatory attr on AD
# and sn is mandatory on OID. sn is not mandatory on Active Directory
SAMAccountName: : :user:sn: : person:
# attributes to map to cn - normally this is the given name
cn: : :person:cn: :person:
AttributeExclusionList
facsimileTelephoneNumber
telephonenumber

Manually Creating New Mapping Files

Oracle recommends using Oracle Enterprise Manager Fusion Middleware Control to create synchronization mapping rules when you create and configure synchronization profiles. You create mapping rules on the Mapping tab described in Creating Synchronization Profiles. The following information is provided for reference if you must create mapping files manually, that is, not using Oracle Enterprise Manager Fusion Middleware Control.

To create new mapping files manually:

1. Identify the containers of interest for synchronization in the source directory.

2. Identify the destination containers to which the objects in the source containers should be mapped. Be sure that the specified container already exists in the directory.

3. Determine the rule to create a DN of the entry to be created in the destination directory. In LDAP-to-LDAP, mapping is normally one-to-one. In non-LDAP-to-LDAP, a domain DN construct rule is required. For example, in the case of synchronizing from a tagged file or Human Resources agent, the mapping rule may be in the form uid=%,dc=mycompany,dc=com. In this case, the uid attribute must be present in all the changes to be applied from Oracle Human Resources. The uid attribute must be specified as a required attribute, as specified in step 6.

4. Identify the objects that you want to synchronize among directories—that is, the relevant object classes in the source and destination directories. In general, objects that get synchronized among directories include users, groups, organizational units, organizations, and other resources. Identify the actual object classes used in the directories to identify these objects.

5. Identify the properties of the various objects that you want to synchronize among directories—that is, the attributes in the LDAP context. All the attributes of an object need not be synchronized. The properties of users that you might want to synchronize are cn, sn, uid, and mail.

6. Define the mapping rules. Each mapping rule has this format:

   <srcAttrName>:<ReqdFlag>:<srcAttrType>:<SrcObjectClass>: <dstAttrName>:<dstAttrType>:<dstObjectClass>: <Mapping Rule>
   

   While defining the mapping rule, ensure the following:

   • Every required attribute has a sequence number. For example, if in step 3 the uid attribute is identified as required, then assign a value of 1 in place of <ReqdFlag>.

   • Every relevant object class has a schema definition on the destination directory.

   • Every mandatory attribute in a destination object class has a value assigned from the source. This is true for standard object classes also, as the different LDAP implementations may not be completely standards-compliant.

   It is not necessary to assign all attributes belonging to a source object class to a single-destination object class. Different attributes of a source object class can be assigned to different attributes belonging to different destination object classes.

   If an attribute has binary values, then specify it as binary in the <attrtype> field.

Mapping rules are flexible. They can include both one-to-many and many-to-one mappings.

• One-to-many

  One attribute in a connected directory can map to many attributes in Oracle Internet Directory. For example, suppose an attribute in the connected directory is Address:123 Main Street/MyTown, MyState 12345. You can map this attribute in Oracle Internet Directory to both the LDAP attribute homeAddress and the LDAP attribute postalAddress.

• Many-to-one

  Multiple attributes in a connected directory can map to one attribute in Oracle Internet Directory. For example, suppose that the Oracle Human Resources directory represents Anne Smith by using two attributes: firstname=Anne and lastname=Smith. You can map these two attributes to one attribute in Oracle Internet Directory: cn=Anne Smith. However, in bidirectional synchronization, you cannot then map in reverse. For example, you cannot map cn=Anne Smith to many attributes.

Supported Attribute Mapping Rules and Examples

The attribute mapping rules supported are:

• Concatenation operator (+): Concatenates two string attributes.

  The mapping rule looks like:

  Firstname,lastname:  :  :  : givenname:  : inetorgperson: firstname+lastname
  

  For example, if the Firstname is John and LastName is Doe in the source, then this rule results in the givenname attribute in the destination with the value JohnDoe.

• OR operator ( | ): Assigns one of the values of the two string attributes to the destination.

  The mapping rule looks like this:

  Fistname,lastname : : : :givenname: :inetorgperson: firstname | lastname
  

  In this example, givenname is assigned the value of firstname if it exists. If the firstname attribute does not exist, then givenname is assigned the value of lastname. If both the values are empty, then no value is assigned.

• bin2b64 ( ): Stores a binary value of the source directory as a base64 encoded value in the destination directory. Typical usage is as follows:

  objectguid: : : :binary: :orclobjectguid: orcladuser:bin2b64(objectguid)
  

  This is required when you need search on the value of (objectguid).

• tolower(): Converts the String attribute value to lowercase.

  firstname: : : :givenname: :inetorgperson: tolower(firstname)
  

• toupper (): Converts the String attribute value to uppercase.

  firstname: : : :givenname: :inetorgperson: toupper(firstname)
  

• trunc(str,char): Truncates the string beginning from the first occurrence of the specified char.

  mail : : : : uid : : inetorgperson : trunc(mail,'@')
  

  For example, if mail is [email protected] in the source, then this rule results in the uid attribute in the destination with the value John.Doe.

• truncl(str, char): Truncates the string up to and including the first occurrence of the specified char. For example:

  mail : : : : uid : : inetorgperson : truncl(mail,'@')
  

• truncr(str, char): Truncates everything in the string that appears on the right side of the specified char. For example:

  mail : : : : uid : : inetorgperson : truncr(mail,'@')
  

• dnconvert (str): Converts DN type attributes if domain mapping is used.

  This example assumes the following domain mapping rule:

  DomainRules
  cn=srcdomain:cn=dstdomain:
  

  For example:

  uniquemember : : : groupofuniquenames : uniquemember : :groupofuniquenames : dnconvert(uniquemember)
  

  In this example, if uniquemember in the source is cn=testuser1,cn=srcdomain, then uniquemember in the destination becomes cn=test user1,cn=dstdomain.

• Literals:

  Userpassword: : :person: userpassword: :person: 'welcome1'
  

Example: Mapping File for a Tagged-File Interface

Based on the preceding discussions, here is a sample mapping file for importing user entries from the Oracle Human Resources database tables by using the tagged-file interface. Note that the source is a non-LDAP directory. This sample file is supplied during installation, at $ORACLE_HOME/ldap/odi/conf/oraclehragent.map.master.

DomainRules
NONLDAP:dc=myCompany,dc=com:uid=%dc=myCompany,dc=com
AttributeRules
firstname: : : :cn: :person
email : : : :cn: :person: trunc(email,'@')
email : 1 : :uid: :person:trunc(email,'@')
firstname,lastname: : : :cn: :person: firstname+","+lastname
lastname,firstname: : : :cn: :person: lastname+","+firstname
firstname,lastname: : : :sn: :person: lastname | firstname
EmployeeNumber: : : :employeenumber: :inetOrgperson
EMail: : : :mail: :inetOrgperson
TelephoneNumber1: : : :telephonenumber: :person
TelephoneNumber2: : : :telephonenumber: :person
TelephoneNumber3: : : :telephonenumber: :person
Address1: : : :postaladdress: :person
state: : : :st: :locality
street1: : : :street: :locality
zip: : : :postalcode: :locality
town_or_city: : : :l: :locality
Title: : : :title: :organizationalperson
#Sex: : : :sex: :person ###

As described earlier, the mapping file consists of keywords and a set of domain and attribute mapping rule entries. The mapping file in this example contains the domain rule NONLDAP:dc=myCompany,dc=com:cn=%,dc=myCompany,dc=com.

• This rule implies that the source domain is NONLDAP—that is, there is no source domain.

• The destination domain (:dc=myCompany,dc=com) implies that all the directory entries this profile deals with are in the domain dc=myCompany,dc=com. Be sure that the domain exists before you start synchronization.

• The domain mapping rule (:uid=%,dc=myCompany,dc=com) implies that the data from the source refers to the entry in the directory with the DN that is constructed using this domain mapping rule. In this case, uid must be one of the destination attributes that should always have a non null value. If any data corresponding to an entry to be synchronized has a null value, then the mapping engine assumes that the entry is not valid and proceeds to the next entry. To identify the entry correctly in the directory, it is also necessary that uid is a single value.

• In the case of the tagged file, the source entry does not have an object class to indicate the type of object to which it is synchronizing. Note that the SrcObjectClass field is empty.

• Every object whose destination is Oracle Internet Directory must have an object class.

• Note that email is specified as a required attribute in the sample mapping file. This is because the uid attribute is derived from the email attribute. Successful synchronization requires the email attribute to be specified in all changes specified in the tagged file as follows:

  Email : 1 : : :uid : : person : trunc(email,'@')
  

• In some cases, the RDN of the DN needs to be constructed by using the name of a multivalued attribute. For example, to construct an entry with the DN of cn=%,l=%,dc=myCompany,dc=com, where cn is a multivalued attribute, the DomainMappingRule can be in this form: rdn,l=%,dc=myCompany,dc=com where rdn is one of the destination attributes having a non null value. A typical mapping file supporting this could have the following form:

  DomainRules
  NONLDAP:dc=us,dc=myCompany,dc=com:rdn,l=%,dc=us,dc=myCompany,dc=com
  AttributeRules
  firstname: : :cn: :person
  email : : : :cn: :person: trunc(email,'@')
  email : 1: : :rdn: :person: 'cn='+trunc(email,'@')
  firstname,lastname: : : :cn: :person: firstname+","+lastname
  lastname,firstname: : : :cn: :person: lastname+","+firstname
  firstname,lastname: : : :sn: :person: lastname | firstname
  EmployeeNumber: : : :employeenumber: :inetOrgperson
  EMail: : : :mail: :inetOrgperson
  TelephoneNumber1: : : :telephonenumber: :person
  TelephoneNumber2: : : :telephonenumber: :person
  TelephoneNumber3: : : :telephonenumber: :person
  Address1: : : :postaladdress: :person
  Address1: : : :postaladdress: :person
  Address1: : : :postaladdress: :person
  state: : : :st: :locality
  street1: : : :street: :locality
  zip: : : :postalcode: :locality
  town_or_city: 2 : : :1: :locality
  Title: : : :title: :organizationalperson
  #Sex: : : :sex: :person
  ###
  

Example: Mapping Files for an LDIF Interface

Sample integration profiles are created as part of the Oracle Directory Integration Platform installation. The property files used to created the sample integration profiles are located in the $ORACLE_HOME/ldap/odi/samples directory. The following is an example of a sample import mapping file:

Sample Import Mapping File

DomainRules
dc=mycompany.oid,dc=com:dc=mycompany.iplanet,dc=com
AttributeRules
# Mapping rules to map the domains and containers
o: : :organization: o: :organization
ou: : :organizationalUnit: ou: : organizationalUnit
dc: : :domain:dc: :domain
# Mapping Rules to map users
uid : : :person: uid: :inetOrgperson
sn: : :person:sn: :person
cn: : :person:cn: :person
mail: :inetorgperson: mail: :inetorgperson
employeenumber: :organizationalPerson: employeenumber: :organizationalperson
c: : :country:c: :country
l: : :locality: l: :locality
telephonenumber: :organizationalPerson: telephonenumber: :organizationalperson
userpassword: : :person: userpassword: :person
uid: : :person: orcldefaultProfileGroup: :orclUserV2
# Mapping Rules to map groups
cn: : :groupofuniquenames:cn: :groupofuniquenames
member: : :groupofuniquenames:member: :orclgroup
uniquemember: : :groupofuniquenames:uniquemember: :orclgroup
owner: : :groupofuniquenames:owner: :orclgroup
# userpassword: :base64:userpassword: :binary:

Notice, in the preceding example that both the source domain and destination domain are specified in the Domain Mapping rule section. In this example, the source and the destination domains are the same. However, you can specify a different destination domain, provided the container exists in the destination directory.

Also notice, in the preceding example, that the attribute rules are divided into two sections: user attribute mapping rules and group attribute mapping rules. Specifying the object class in a mapping rule helps to uniquely map a specific attribute of an object.

Updating Mapping Rules

You can customize mapping rules by adding new ones, modifying existing ones, or deleting some from the mapping rule set specified in the orclodipAttributeMappingRules attribute. In general, to perform any of these operations, you identify the file containing the mapping rules, or store the value of the attribute for a file by using an ldapsearch command as described in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

Writing Custom Plug-Ins

To extend mapping functionality using custom plug-ins you must implement the oracle.ldap.odip.util.mapapi.IMapOperation interface, which requires implementing the evaluate method as follows:

Vector evaluate(Vector operands);

The operands argument is a vector. Elements of the operands vector can be one of the following, based on the plug-in invocation given in the mapping rule:

• Vector of values (attributes passed as argument for the plug-in)

• String (String literal is passed as argument for the plug-in)

• Character (Character literal)

Return type is a Vector. All elements of this Vector must be Strings or byte arrays. If you want to return a single string, a new vector of size 1 must be created and the string has to be added to it. This restriction is enforced to allow multi-valued attributes.

For example:

cn,sn: : :person:description: :person:PLUGIN#MyPlugin(cn, sn, “Mr”)

The plug-in class MyPlugin should implement Vector evaluate(Vector operands) method. As per the plug-in invocation in the above mapping rule, the following are the elements of operands:

• element1 is a Vector containing all values of cn (Even if cn has only a single value)

• element2 is a Vector containing all values of sn (Even if sn has only a single value)

• element3 is a String literal "Mr"

Mapping Plug-In Evaluation Constraints

• If an attribute has multiple values, the corresponding plug-in will be called only once with all the attribute values stored in a Vector. The plug-in will not be called once per each attribute value.

• Empty String literals (" ") or Character literals (' ') will be ignored.

• You must identify the type of each element in the vector operands of the evaluate() method and process accordingly, as per the plug-in invocation.

• A combination of plug-ins and the existing mapping rule operators or functions is not supported. For example, the following combination is not supported as mapping rule:

  Plugin#MyPlugin(cn, sn) + givenanme 
  toupper(Plugin#(MyPlugin(cn,sn))
  Plugin#TempPlugin1(cn) + Plugin#TempPlugin2(sn)
  

• Oracle recommends that Mapping plug-in invocation in different attribute rules follow the same invocation signature. The following example is not recommended and is highly error prone because Myplugin has different invocation signatures:

  sn: : :person:givenname: :person:PLUGIN#Myplugin(sn,"Mr")
  cn: : :person:description: :person:PLUGIN#Myplugin(cn)
  

Adding Mapping Plug-Ins

To add a mapping plug-in to Oracle Directory Integration Platform:

1. If it is running, stop the WebLogic Managed Server hosting Oracle Directory Integration Platform.

2. Copy the mapping plug-in JAR file to the /APP-INF/lib/ directory in the path where the Oracle Directory Integration Platform application was exploded. For example:

   MW_HOME/user_projects/domains/DOMAIN_NAME/servers/MANAGED_SERVER_NAME/tmp/
   _WL_user/DIP_VERSION_NUMBER/RANDOM_CHARACTERS/APP-INF/lib/
   

3. Start the WebLogic Managed Server hosting Oracle Directory Integration Platform.

Applications of Mapping Plug-Ins

This section describes various applications of Mapping plug-ins, including:

• Support for New Mapping Operations

• Support for Multiple Literal Values

Example Plug-In Usage

This section provides examples of plug-in usage.

Example 1: Attribute Mapping Rule

cn: : :person:initials: :person:PLUGIN#PluginSamp1(cn)

Example 1: Corresponding Plug-In Implementation

Vector evaluate(Vector operands)
{
Vector all_cnValues = (Vector)operands.get(0);
Vector result =  new Vector();
        ….
               ….
              //All the elements of this result must be strings.
              return result;    
}

Example 2: Attribute Mapping Rule

cn: : :person:givenname: :person:PLUGIN#Myplugin(cn,"Mr")

Example 2: Corresponding Plug-In Implementation

Vector evaluate(Vector operands)
{
Vector all_cnValues = (Vector)operands.get(0);
String strOperand = (String)operands.get(1);
Vector result =  new Vector();
 
for(int i=0; i<all_cnValues.size(); i++)
{
String cnValue = (String) all_cnValues.get(i);
String givenNameNewValue = strOperand + cnValue;
result.add(givenNameNewVlaue);
                }
              //All the elements of this result must be strings.
              return result;
}

Example 3: Attribute Mapping Rule

mail: : :inetorgperson:mail: :inetorgperson: Plugin#MyPlugin(mail, '@')

Example 3: Corresponding Plug-In Implementation

Vector evaluate(Vector operands)
{
                Vector all_mailValues = (Vector) operands.get(0);
                Character charOperand = (Character) operands.get(1);
                char charOperandValue = charOperand.charValue();
Vector result =  new Vector();
        ….
               ….
               ….
        return result;
}

Example 4: Attribute Mapping Rule

cn,sn,mail: : :inetorgperson:description: :inetorgperson Plugin# MyPlugin(cn, sn, mail)

Example 4: Corresponding Plug-In Implementation

Vector evaluate(Vector operands)
{
                Vector all_cnValues = (Vector) operands.get(0);
                Vector all_snValues = (Vector) operands.get(1);
                Vector all_mailValues = (Vector) operands.get(2);

                Vector result = new Vector();
                …
                …
                …

                return result;
}

Filtering Changes with an LDAP Search

For connected directories that do not support change logs, the latest footprint of the entries are obtained by performing an LDAP search. Because an LDAP search that is performed with objectclass=* will return all entries in a given tree or subtree, to retrieve only the objects of interest for synchronization, you must provide a filter using LDAP filter syntax. For example, you can assign a search filter to the orclOdipConDirMatchingFilter attribute. You specify the filter as searchfilter=LDAP_SEARCH_FILTER.

The following example creates an LDAP search filter that retrieves organizational units, groups, and users, but not computers:

searchfilter=(|(objectclass=group)(objectclass=organizationalUnit)
(&(objectclass=user)(!(objectclass=computer))))

Filtering Changes from a Change Log

For connected directories that store changes in a change log, you can use the following simple operators, which are provided by Oracle Directory Integration Platform, to specify a matching filter for either the Connected Directory Matching Filter (orclODIPConDirMatchingFilter) or the OID Matching Filter (orclODIPOIDMatchingFilter):

• = (equal operator)

• != (not equal operator)

You can use the preceding operators with either LDAP or non-LDAP directories, provided they obtain incremental changes from a change log. Wildcards and pattern matching are not supported with the preceding operators if you do not use the searchfilter attribute. However, when multiple operator pairs are including in the filter, the expression is evaluated as a logical AND operation. For example, the following expression includes four operator pairs:

(objectclass=group)(objectclass=organizationalUnit)
(objectclass=user)(objectclass!=computer)
 

The preceding expression evaluates as follows:

objectclass is equal to group
AND objectclass is equal to organizationalUnit
AND objectclass is equal to user
AND objectclass is NOT equal to computer
 

For connected directories that store changes in a change log, a matching filter can synchronize changes for only the attributes that appear in the change log. If you include attributes in a matching filter that do not appear in the change log, the search operation will fail. For this reason, matching filters are of limited use for connected directories that store incremental changes in a change log.