Oracle® Fusion Middleware Administrator's Guide for Oracle Directory Integration Platform 11g Release 1 (11.1.1) E10031-03 |
|
![]() Previous |
![]() Next |
This chapter explains how to configure directory synchronization and how to format mapping rules. It contains these topics:
See Also: Chapter 3, "Administering Oracle Directory Integration Platform" for information on using Oracle Enterprise Manager Fusion Middleware Control. |
Before deploying a connector, you register it in Oracle Internet Directory. This registration involves creating a synchronization profile, which is stored as an entry in the directory. Refer to "Creating Synchronization Profiles" for information about creating a directory synchronization profile using Oracle Enterprise Manager Fusion Middleware Control.
Attributes in a synchronization profile entry belong to the object class orclodiProfile
. The only exception is the orclodiplastappliedchangenumber
attribute, which belongs to the orclchangesubscriber
object class.
The 2.16.840.1.113894.7
object identifier prefix is assigned to platform-related classes and attributes.
The various synchronization profile entries in the directory are created under the container cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory
. For example, a connector called OracleHRAgent
is stored in the directory as orclodipagentname=OracleHRAgent,cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory
.
When you install Oracle Directory Integration Platform, template profiles are created for synchronization with the different directory types, including:
Microsoft Active Directory 2003
Microsoft Active Directory Lightweight Directory Service (AD LDS) Version 1 (previously known as Active Directory Application Mode or ADAM)
IBM Tivoli Directory Server 6.2
Sun Java System Directory Server 6.3
Novell eDirectory 8.8
OpenLDAP-2.2
LDIF files
Tagged files
The property and mapping files used to create the template profiles are available in the $ORACLE_HOME/ldap/odi/conf directory.
You can configure the connection details for a third-party directory by creating or editing a synchronization profile using Oracle Enterprise Manager Fusion Middleware Control. To use one of the sample synchronization profiles that was creating during installation, be sure to specify the correct connection details. In addition to specifying the connection details, you must also ensure that the user account in the third-party directory has the necessary privileges to read user and group information.
You can also create the profiles based on the template properties file provided during installation. If you are doing this, then you must specify the connection details in the odip.profile.condirurl
, and odip.profile.condiraccount
properties of the profile. You will be prompted for the password.
In addition to specifying the connection details, you must also ensure that the user account in the third-party directory has the necessary privileges to read user and group information.
Each third-party directory requires a different configuration for getting deleted entries. Refer to the third-party directory's documentation to set up the tombstone configuration and privileges required to read tombstone entries. For example, with Microsoft Active Directory, you must also ensure that the user account has the privileges to replicate directory changes for every domain of the forest monitored for changes. You can do this by one of the following methods:
Grant to this account Domain Administrative permissions
Make this account a member of the Domain Administrator's group
Grant to this account Replicating Directory Changes permissions for every domain of the forest that is monitored for changes
To grant this permission to a non-administrative user, follow the instructions in the "More Information" section of the Microsoft Help and Support article "How to Grant the 'Replicating Directory Changes' Permission for the Microsoft Metadirectory Services ADAM Service Account" available at http://support.microsoft.com/
.
Some of the most important pieces of a directory synchronization profile include the connection details you assign to the properties listed in Table 6-1:
Table 6-1 Connection Detail Properties
Property | Description |
---|---|
|
The URL of the connected directory:
|
|
The DN or account name used to connect to the third-party directory |
Notes:
|
This section discusses how to configure mapping rules. It contains these topics:
You use the mapping rules attribute to specify how to convert entries from the source to the destination. Oracle Internet Directory must either be the source or the destination. When converting the entries, there are three types of mapping rules: domain rules, attribute rules, and reconciliation rules. These mapping rules allow you to specify distinguished name mapping, attribute-level mapping, and reconciliation rules. Note that reconciliation rules are only used with Novell eDirectory and OpenLDAP. For more information on using reconciliation rules, see Chapter 22, "Integrating with Novell eDirectory or OpenLDAP".
Mapping rules are organized in a fixed, tabular format, and you must follow that format carefully. Each set of mapping rules appears between a line containing only the word DomainRules or AttributeRules and a line containing only three number signs (###).
DomainRules srcDomainName1: [dstDomainName1]: [DomainMappingRule1] srcDomainName2: [dstDomainName2]: [DomainMappingRule2] [DomainExclusionList] srcDomainForExclusion1 srcDomainforExclustion2 ### AttributeRules srcAttrName1:[ReqAttrSeq]:[SrcAttrType]:[SrcObjectClass]:[dstAttrName1]: [DstAttrType]:[DstObjectClass]:[AttrMappingRule1] srcAttrName1,srcAttrName2:[ReqAttrSeq]:[SrcAttrType]:[SrcObjectClass]: [dstAttrName2]:[DstAttrType]:[DstObjectClass]:[AttrMappingRule2] [AttributeExclusionList] exclusionAttribute1 exclusionAttribute2 ###
The expansion of srcAttrName1
and srcAttrName2
in the preceding example should be on a single, unwrapped long line.
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.
Table 6-2 Domain Rule Components
Component Name | Description |
---|---|
|
Name of the domain or container of interest. Specify NONLDAP for sources other than LDAP and LDIF. |
|
Name of the domain of interest in the destination. Specify this component if the container for the entries in the destination directory is different from that in the source directory. If the value assigned to If not specified, this field assumes the value of |
|
This rule is used to construct the destination DN from the source domain name, from the attribute given in This field is meaningful only when importing to Oracle Internet Directory, or when exporting to an LDIF file or another external LDAP-compliant directory. Specify this component if any part of an entry's DN in the destination directory is different from that in the source directory entry. This component is optional for LDAP-to-LDIF, LDAP-to-LDAP, or LDIF-to-LDAP synchronizations. If it is not specified, then the source domain and destination domain names are considered to be the same. |
Example 6-1 Example of Distinguished Name Mapping
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.
Example 6-2 Example of One-to-One Distinguished Name Mapping
For one-to-one mapping to occur, the DN in the third-party directory must match that in Oracle Internet Directory. In this example, the DN in the third-party directory matches the DN in Oracle Internet Directory. More specifically:
The third-party directory host is in the domain us.mycompany.com
, and, accordingly, the root of the third-party directory domain is us.mycompany.com
. A user container under the domain would have a DN value cn=users,dc=us,dc=mycompany,dc=com
.
Oracle Internet Directory has a default realm value of dc=us,dc=mycompany,dc=com
. This default realm automatically contains a users
container with a DN value cn=users,dc=us,dc=mycompany,dc=com
.
Because the DN in the third-party directory matches the DN in Oracle Internet Directory, one-to-one distinguished name mapping between the directories can occur.
If you plan to synchronize only the cn=users
container under dc=us,dc=mycompany,dc=com
, then the domain mapping rule is:
Distinguished Name Rules cn=users,dc=us,dc=mycompany,dc=com:cn=users,dc=us,dc=mycompany,dc=com
This rule synchronizes every entry under cn=users,dc=us,dc=mycompany,dc=com
. However, the type of object synchronized under this container is determined by the attribute-level mapping rules that follow the DN Mapping rules.
If you plan to synchronize the entry cn=groups,dc=us,dc=mycompany,dc=com
under cn=users,dc=us,dc=mycompany,dc=com
then the domain mapping rule is as follows:
cn=groups,dc=us,dc=mycompany,dc=com:cn=groups,cn=users,dc=us,dc=mycompany,dc=com
You can insert the DomainExclusionList
header in map files and identify domains to be excluded during bootstrap and synchronization. Domains listed in the DomainExclusionList
will be excluded during bootstrap and synchronization.
Note: The distinguished names (DNs) listed in thedomainexclusionlist identify the DNs of the containers in the source directory. |
The following is an example of the DomainExclusionList
header with example domains to exclude:
DomainExclusionList OU=myou,OU=test,DC=mycompany,DC=com OU=mynewou,OU=test,DC=mycompany,DC=com
Example 6-3, "Example Map File Using DomainExclusionList and AttributeExclusionList Headers" shows an example map file that includes the DomainExclusionList
header. In this example, the entries under RDN OU=myou, OU=rfi6894748, DC=imtest, DC=com and OU=mynewou, OU=rfi6894748, DC=imtest, DC=com
will be excluded.
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 (###
).
Table 6-3 Components in Attribute Rules
Component Name | Description |
---|---|
|
For LDAP-compliant directory repositories, this parameter refers to the name of the attribute to be translated. For Oracle Database repositories, it refers to the For other repositories this parameter can be appropriately interpreted. |
|
Indicator of whether the source attribute must be passed to the destination. When entries are synchronized between Oracle Internet Directory and the connected directory, some attributes need to be used as synchronization keys. This field indicates whether the specified attribute is being used as a key. If so, regardless of whether the attribute has changed or not, the value of the attribute is extracted from the source. A nonzero integer value should be placed in this field if the attribute needs to be always passed on to the other end. |
|
This parameter refers to the attribute type—for example, integer, string, binary—that validates the mapping rules. |
|
If the source of the shared attribute is an LDAP-compliant directory, then this parameter names the object class to which the attribute belongs. If the source of the shared attribute is an Oracle Database repository, then this parameter refers to the table name and is mandatory. For other repositories, this parameter may be ignored. |
|
Optional attribute. If it is not specified, then the For LDAP-compliant directories, this parameter refers to the name of the attribute at the destination. For Oracle Database repositories, it refers to the ColumnName in the table specified by the For other repositories, this parameter can be appropriately interpreted. |
|
This parameter refers to the attribute type—for example, integer, string, binary. Note that it is up to you, the administrator, to ensure the compatibility of the source and destination attribute types. Oracle Directory Integration Platform does not ensure this compatibility. |
|
For LDAP-compliant directories, this parameter refers to the object class to which the attribute belongs, and is optional. For Oracle Database repositories, it refers to the table name, and is mandatory. For other repositories this parameter may be ignored. |
|
Optional arithmetic expression with the following operators and functions: Operators: + and | Functions:
If nothing is specified, then the source attribute value is copied as the value of the destination attribute. Literals can be specified with single quotation marks ('') or with double quotation marks (""). |
To enter mapping rules in a synchronization profile, edit a file that strictly follows the correct format.
Note: When attributes and object classes are defined in the mapping file, it is assumed that source directories contain the respective attributes and object classes defined in the schema.If a parent container is selected for synchronization, then all its children that match the mapping rules are likewise synchronized. Child containers cannot be selectively ignored for synchronization. |
You can insert the AttributeExclusionList
header in map files and identify attributes to be excluded during bootstrap and synchronization. Attributes listed in the AttributeExclusionList
will be excluded during bootstrap and synchronization.
The following is an example of the AttributeExclusionList
header with example attributes to exclude:
AttributeExclusionList facsimileTelephoneNumber telephonenumber
Example 6-3 shows an example map file that includes both the DomainExclusionList
and AttributeExclusionList
headers. In this example, the entries under RDN OU=myou, OU=rfi6894748, DC=imtest, DC=com and OU=mynewou, OU=rfi6894748, DC=imtest, DC=com
will be excluded, and all filtered entries will exclude (not contain) the facsimileTelephoneNumber
and telephonenumber
attributes.
Example 6-3 Example Map File Using DomainExclusionList and AttributeExclusionList Headers
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
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:
Identify the containers of interest for synchronization in the source directory.
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.
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.
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.
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
.
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.
See Also: The mapping file examples at the end of this chapter |
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 John.Doe@acme.com
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'
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 ###
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.
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.
To add a new entry to the mapping rules file, edit this file and add a record to it. To do this:
Identify the connected directory attribute name and the object class that needs to be mapped to Oracle Internet Directory.
Identify the corresponding attribute name in Oracle Internet Directory and the object class to which it needs to be mapped.
Generate the mapping rule elements indicating the conversion that needs to be done on the attribute values.
Load the attribute mapping rule file to the synchronization profile using the managesyncprofiles command.
For example, if the e-mail attribute of an entry in the source directory needs to be mapped to the unique identifier of the destination, then it can be:
Email: : : inetorgperson: uid: : person:
After you identify an entry to be modified in the mapping rules file, generate the mapping rule element for the desired conversion of attribute values.
After you identify an entry to be deleted in the mapping rules file, you can either delete the entry from the file or comment it out by putting a number sign (#) in front of it.
See Also:
|
You can extend mapping functionality using custom plug-ins. The oracle.ldap.odip.util.mapapi.IMapOperation Java interface is defined to support plug-ins for new mapping operations. This topic explains Oracle Directory Integration Platform support for custom plug-ins to extend mapping functionality and contains the following sections:
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"
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)
To add a mapping plug-in to Oracle Directory Integration Platform:
If it is running, stop the WebLogic Managed Server hosting Oracle Directory Integration Platform.
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/
Start the WebLogic Managed Server hosting Oracle Directory Integration Platform.
This section describes various applications of Mapping plug-ins, including:
Applications can implement their own mapping operations that are not supported internally by the mapping framework.
Support for Conditional Mapping
You can support attribute mapping based on a condition. For example, the application can support a mapping rule where if the credential
attribute is present, then orclpassword
must be set to ENABLED
, and if not present, the orclpassword
must be set to DISABLED
. This logic can be supported by implementing a plug-in to assign this value. The mapping rule should be as follows:
credential: : :UserType:orclisenabled::orcluserv2:ConditionalAttrBasedOnPresence(credential)
You can support DN container mapping based on a condition. For example, users must be mapped to container ou=sales,dc=acme,dc=com
if department is Sales
and mapped to container ou=IT,dc=acme,dc=com
if department is IT
. To support this mapping:
The DomainRules section can have a construction rule like:
NONLDAP:dc=acme,dc=com:cn=%,ou=%,dc=acme,dc=com
The AttributeRules section can have a rule with a plug-in operation to map ou as follows:
department: : :UserType:ou: :orcluserv2:ConditionalOUMapping(department)
The current mapping framework only supports specifying a single literal value for an attribute. However, there might be a need to specify more than one literal value when an attribute can have multiple default values. For example, in case of Microsoft Exchange, there is a showInAddressBook attribute which can have more than one value. This can also be implemented using plug-ins.
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; }
By default, a connector retrieves changes to all objects in the container configured for synchronization. However, you may want to synchronize only certain types of changes, such as changes to just users and groups. While mapping rules allow you to specify how entries are converted from one directory to another, you can also filter objects that are synchronized among directories. Before changes from a connected directory are imported into Oracle Internet Directory, they can be filtered with the Connected Directory Matching Filter (orclODIPConDirMatchingFilter
) attribute in the synchronization profile. Similarly, before changes are exported from Oracle Internet Directory to a connected directory, they can be filtered with the OID Matching Filter (orclODIPOIDMatchingFilter
) attribute. For both attributes, you can specify a filter for connected directories that either obtain incremental changes through an LDAP search or that store changes in a change log, as described in the following sections:
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))))
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)
Note: Connected directories that obtain incremental changes through an LDAP search can also use the preceding operators without thesearchfilter attribute. However, you can only specify a single expression or the search will fail. |
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.
Table 6-4 lists where to find the various files used during synchronization. By default, when file based interfaces (Tagged/LDIF) are used for synchronization, the files are read from and written to the following locations.
Table 6-4 Location and Names of Files
File | File Name |
---|---|
Import data file |
|
Export data file |
$ORACLE_HOME/ldap/odi/data/export/Profile_Name.dat |
For example, the name of the data file of the Oracle Human Resources profile is oraclehrprofile.dat
.