10g (9.0.4)
Part Number B12118-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Internet Directory Administrator's Guide 10g (9.0.4) Part Number B12118-01 |
|
Oracle Directory Synchronization Service , 2 of 4
This section contains these topics:
To synchronize between Oracle Internet Directory and a connected directory, the Oracle Directory Integration and Provisioning platform relies on a prepackaged connectivity solution called a connector. Minimally, this connector consists of a directory integration profile containing all the configuration information required for synchronization.
When synchronizing between Oracle Internet Directory and a connected directory, the Oracle Directory Integration and Provisioning platform uses one of these interfaces: DB, LDAP, tagged, or LDIF. If the connected directory uses one of these interfaces, then the connector requires only a directory integration profile for synchronization to occur. For example, the SunONE connector provided with Oracle Internet Directory uses the LDAP interface to read the changes from the SunONE Directory Server. The changes are in the format specific to SunONE Directory Server and can be determined by doing an ldapsearch in the SunONE Directory Server.
If a connected directory cannot use one of the interfaces supported by the Oracle Directory Integration and Provisioning platform, then, in addition to the directory integration profile, it requires an agent. The agent transforms the data from one of the formats supported by the Oracle Directory Integration and Provisioning platform into one supported by the connected directory. An example is the Oracle Human Resources connector. It has both a prepackaged integration profile and an Oracle Human Resources agent. To communicate with Oracle Internet Directory, the agent uses the tagged file format supported by the Oracle Directory Integration and Provisioning platform. To communicate with the Oracle Human Resources system, it uses SQL (through an OCI interface).
Depending on where the changes are made, synchronization can occur:
Regardless of the direction in which the data flows, it is assumed that:
Oracle Internet Directory maintains a change log in which it stores incremental changes made to directory objects. It stores these changes sequentially based on the change log number.
Synchronization from Oracle Internet Directory to a connected directory makes use of this change log. Consequently, when running the Oracle directory integration and provisioning server, you must start Oracle Internet Directory with the default setting in which change logging is enabled. If change logging is disabled, you can enable it by using the -l flag in the OID Control Utility (OIDCTL) as described in "Starting an Oracle Directory Server Instance".
Each time the Oracle Directory Synchronization Service processes a synchronization profile, it:
The appropriate entries or attributes are then updated in that connected directory. If the connected directory does not use DB, LDAP, tagged, or LDIF formats directly, then the agent identified in its profile is invoked. The number of the last change successfully used is then stored in the profile.
Periodically, Oracle Internet Directory purges the change log after all profiles have used what they need, and identifies where subsequent synchronization should begin.
When a connected directory uses DB, LDAP, tagged, or LDIF formats directly, changes to its entries or attributes can be automatically synchronized by the Oracle Directory Synchronization Service. Otherwise, the connector has an agent in its synchronization profile, which writes the changes to a file in the LDIF or tagged format. The Oracle Directory Synchronization Service then uses this file of connected directory data to update Oracle Internet Directory.
Some connected directories cannot receive data by using any of the interfaces supported by Oracle Internet Directory. Profiles for this type of directory contain an attribute identifying a separate program for synchronization, called an agent. The agent translates between the connected directory's unique format and a DB, LDAP, tagged, or LDIF file containing the synchronization data. The agent, as identified in the profile, is invoked by the Oracle Directory Synchronization Service.
When exporting data from Oracle Internet Directory to this type of connected directory, the Oracle Directory Synchronization Service creates the necessary file in the tagged or LDIF format. The agent then reads that file, translates it into the correct format for the receiving connected directory, and stores the data in that directory.
When importing data from this type of connected directory to Oracle Internet Directory, the agent creates the necessary tagged or LDIF format file. The Oracle Directory Synchronization Service then uses this file data to update the Oracle Internet Directory.
A directory integration profile for synchronization, called a directory synchronization profile, contains all the configuration information required for synchronization including:
Some connected directories only receive data from Oracle Internet Directory--that is, they participate in export operations only. Others only supply data to Oracle Internet Directory--that is, they participate in import operations only. Still others participate in both import and export operations.
A separate profile is used for each direction--that is, one profile for information coming into Oracle Internet Directory, and another for information going from Oracle Internet Directory to connected directories.
Some connected directories can receive data in any of the interfaces built into the Oracle Directory Integration and Provisioning platform. These interfaces include LDAP, tagged, DB (for read-only), and LDIF. For these connected directories, the Oracle Directory Synchronization Service performs the synchronization itself directly, using the information stored in the profile.
In a directory synchronization environment, a typical set of entries from one domain can be moved to another domain. Similarly, a set of attributes can be mapped to another set of attributes.
Mapping rules govern the conversion of attributes between a connected directory and Oracle Internet Directory. Each connector stores a set of these rules in the orclodipAttributeMappingRules attribute of its synchronization profile. The Oracle directory integration and provisioning server uses these rules to map attributes as needed when exporting from the directory and interpreting data imported from a connected directory or file. When the Oracle directory integration and provisioning server imports changes into Oracle Internet Directory, it converts the connected directory's change record into an LDAP change record following the mapping rules. Similarly, during export, the connector translates Oracle Internet Directory changes to the format understood by the connected directory.
These details include such information about the connected directory as host, port, mode of connection--that is, either SSL or non-SSL--and the connected directory credentials.
Although the synchronization profile stores most of the information needed by a connector to synchronize Oracle Internet Directory with connected directories, some connectors may need more. This is because some operations might require additional configuration information at runtime.
You can store such additional connector configuration information wherever and however you want. However, the Oracle Directory Integration and Provisioning platform enables you to store it in the synchronization profile as an attribute called orclODIPAgentConfigInfo. Its use is optional--that is, if a connector does not require such information, then simply leave this attribute empty. If such information would be useful, you can load it into this attribute by using either the Directory Integration and Provisioning Assistant or the script named ldapuploadagentfile.sh. The type and format of the data stored in the additional configuration information attribute are determined by each executable's needs.
This configuration information can pertain to the connector, the connected directory, or both. Oracle Internet Directory and Oracle directory integration and provisioning server do not modify this information. When the connector is invoked, the Oracle directory integration and provisioning server simply provides it with the information in this attribute as a temporary file.
|
See Also:
|
Before deploying a connector, you register it in Oracle Internet Directory. This registration involves creating a directory synchronization profile, which is stored as an entry in the directory. The attributes of this profile are listed and described in Table B-20.
To create the profile, you can use either Oracle Directory Manager or the Directory Integration and Provisioning Assistant as described in subsequent sections of this chapter. If you use the Directory Integration and Provisioning Assistant, then you do not need to perform a separate operation to upload the mapping and configuration files.
Most of the information needed to synchronize the data with the connected directory--such as account name, password, host name, port number--is stored in the synchronization profile. However, if the connector execution requires any additional information, it can be stored in the orclOdipAgentConfigInfo attribute of the synchronization profile entry as described in the previous section, "Directory Synchronization Profiles".
Attributes in a synchronization profile entry belong to the object class orclodiProfile. The only exception is the orclodiplastappliedchangenumber attribute, which belongs to the object class orclchangesubscriber.
The Object Identifier prefix 2.16.840.1.113894.7 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.
The mapping rules attribute enables you to specify how to convert entries from one directory to another. You can specify domain-level mapping and attribute-level mapping. This attribute is assumed to be in the format of a file as described in this section.
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 and a line containing only the characters ###. The fields within each rule are delimited by a colon (:).
DomainRulessrcDomainName1: [dstDomainName1]: [DomainMappingRule1]srcDomainName2: [dstDomainName2]: [DomainMappingRule2]AttributeRulessrcAttrName1:[ReqAttrSeq]:[SrcAttrType]:[SrcObjectClass]:[dstAttrName1]:[DstAttr Type]:[DstObjectClass]:[AttrMappingRule1]srcAttrName1,srcAttrName2:[ReqAttrSeq]:[SrcAttrType]:[SrcObjectClass]:[dstAttrNa me2]:[DstAttrType]:[DstObjectClass]:[AttrMappingRule2]###
where the expansion of each srcAttrName1 and srcAttrName2 would be a single, unwrapped long line.
The domain rule specifications appear after a line containing only the keyword DomainRules. Each domain rule is represented with the components, separated by colons, that are described in Table 33-1.
The attribute rule specifications appear after a line containing only the keyword AttributeRules. Each attribute rule is represented with the components, separated by colons, and described in Table 33-2. The attribute rule specifications end with a line containing only the characters ###.
In a newly created synchronization profile, mapping rules are empty. To enter mapping rules, edit a file that strictly follows the correct format.
To create a new mapping file, follow these steps:
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.
cn, sn, uid, mail.
<srcAttrName>:<ReqdFlag>:<srcAttrType>:<SrcObjectClass>: <dstAttrName>:<dstAttrType>:<dstObjectClass>: <Mapping Rule>
While defining the mapping rule, ensure the following:
uid attribute is identified as required, then assign a value of 1 in place of <ReqdFlag>.
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.
The attribute mapping rules supported are:
Concatenation (+): Used to concatenate 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.
The Mapping rule looks like:
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 ( ): Used to store 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(): Convert the String attribute value to lowercase.
firstname: : : :givenname: :inetorgperson: tolower(firstname)
toupper (): Convert the String attribute value to uppercase.
firstname: : : :givenname: :inetorgperson: toupper(firstname)
trunc(str,char): Truncate 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): Truncate the string up to and including 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 acme.com.
trunc(str1, str2): Truncate the string beginning with the first occurrence of the specified string
mail : : : : uid : : inetorgperson : trunc(mail, "@")
dnconvert (str): Used for DN type attributes if domain mapping is used.
For example:
uniquemember : : : groupofuniquenames : uniquemember : :groupofuniquenames : dnconvert(uniquemember)
In this example, if uniquemember in the source is cn=test user1,cn=srcdomain, then uniquemember in the destination becomes cn=test user1,cn=dstdomain.
if the domain mapping rules was like this.
DomainRules cn=srcdomain:cn=dstdomain:
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. 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.
: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 the start of synchronization.
:uid=%,dc=myCompany,dc=com) implies that the data from the source should refer 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 invalid and proceeds to the next entry. To identify the entry correctly in the directory, it is also necessary that uid should be single-valued.
SrcObjectClass field is empty.
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,'@')
cn=%,l=%,dc=myCompany,dc=com, where cn is a multivalued attribute, the DomainMappingRule can be of 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 ###
Mapping rules are flexible: They can include both one-to-many and many-to-one mappings.
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.
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.
A set of sample integration profiles are created as part of installation by using the Directory Integration and Provisioning Assistant. The properties file used for creating the profile is located in the directory $ORACLE_HOME/ldap/odi/samples.
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:
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 "ldapsearch Syntax".
You cannot edit the mapping rules in Oracle Directory Manager. Instead, mapping rules are stored in a file that you upload to the directory as a value of the attribute. To upload the mapping file, use the Directory Integration and Provisioning Assistant or the utility ldapuploadagentfile.sh. Once you have created and uploaded the mapping file, you can maintain a copy of it in the $ORACLE_HOME/ldap/odi/conf directory, and upload it again after any future update.
dipassistant mp -profile profile name odip.profile.mapfile=map file
To add a new entry to the mapping rules file, edit this file and add a record to it. To do this:
For instance, 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 hash mark (#) in front of it.
|
See Also:
|
|
Note: To run shell script tools on the Windows operating system, you need one of the following UNIX emulation utilities:
|
Table 33-3 tells you where to find the various files used in the directory integration profile and during synchronization.
For example, the datafile name of the Oracle Human Resources connector is oraclehrprofile.dat.
|
 Copyright © 1999, 2003 Oracle Corporation. All Rights Reserved. |
|