This chapter describes the steps you must perform to transition to OUD and it contains the following topics:
Section 4.5, "Step 4: Transitioning Directory Configuration"
Section 4.6, "Step 5: Transitioning User Data and Directory Metadata"
Section 4.9, "Step 8: Redirecting Traffic to the OUD Topology"
This chapter explains the steps you must perform to transition to OUD. You must perform all steps in this chapter regardless of which transition strategy you are using.
Note:
If you are using the Direct Strategy, then skip to: Section 4.7, "Step 6: Deploying Replication Gateway or DIP."You must first install OUD 11g Release 2 (11.1.2) and create a new instance. The new OUD instance is configured and initialized during the transition steps, and then used as a base to configure and deploy additional instances in a replicated topology.
For instructions on installing an OUD instance see: The Installation Guide for Oracle Unified Directory.
You can set up a new OUD instance using one of the following methods:
Graphical User Interface (GUI)
Command Line Interface (CLI)
Batch mode
In order for the ds2oud
command to work successfully, you must configure the new instance with no suffixes.
To set up your directory server by using the GUI or by using the CLI, the suffix/base dn
must be left blank. Refer to the Installation Guide for Oracle Unified Directory for setting up the directory server using GUI and CLI.
When the directory server is set up in batch mode, the -b
options must not be specified.
Note:
Theds2oud
command is located in <OUD_INSTANCE>/OUD/bin
. OUD_INSTANCE
is the path of the base OUD instance created in Section 4.2, "Step 1: Creating a Reference OUD Instance."ds2oud
to Diagnose the (O)DSEE Directory Server, Configuration, Schema and DataDuring this step, existing (O)DSEE settings are analyzed to identify the features that do not have an identical counterpart on the OUD side and cannot be transitioned automatically. These features will require special attention during transition.
Ensure that you have the LDAP administrative password to access the (O)DSEE directory server. No changes will be performed on this server during the diagnostic cycle. For further information, see Understanding Root Users and the Privilege Subsystem in the Administrator's Guide for Oracle Unified Directory.
Ensure that you have an LDIF file containing the user data exported from your (O)DSEE directory server. For information on exporting LDIF files, go to the following:
For information on exporting LDIF files for 5.2, refer to the "Exporting Databases" section in the Sun ONE Directory Server 5.2 Reference Manual. You can access the Reference Manual on the Sun Java Enterprise System 2003Q4 web site located at http://docs.oracle.com/cd/E19199-01/
For information on exporting LDIF files for 6.x, refer to the "Exporting to LDIF" section in the Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide. You can access the Administration Guide in the Sun Java System Directory Server Enterprise Edition 6.3 web site located at http://docs.oracle.com/cd/E19261-01/
For information on exporting LDIF files for 7.0, refer to the "Exporting to LDIF" section in the Sun Directory Server Enterprise Edition 7.0 Administration Guide. You can access the Administration Guide in the Sun Directory Server Enterprise Edition 7.0 web site located at http://docs.oracle.com/cd/E19424-01/
For information on exporting LDIF files for 11g, refer to the "Exporting to LDIF" section in the Oracle Directory Server Enterprise Edition Administration Guide. You can access the Administration Guide in the Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.5) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Ensure that you have access to a copy of the user schema extensions (99user.ldif)
holding the (O)DSEE server schema extension.
This diagnostic process is performed by running the ds2oud
tool which is shipped with OUD. The number of differences detected by ds2oud
in diagnostic mode can be used to estimate complexity and transition effort.
Run the following ds2oud
command to diagnose your server configuration that must be transitioned to OUD:
$ ds2oud --diagnose -h host1.example.com -p 1389 \ -D "cn=directory manager" -j pwdfile
In the command above, host1 is the (O)DSEE server, not the OUD server.
The --diagnose subcommand identifies the following elements of your directory server configuration:
Unsupported plug-ins
Extensions to the default schema
The type of password policy used which may have an impact if you use the Replication Gateway Strategy
Encrypted attributes
Index settings
Global configuration parameters
For each element above, ds2oud
identifies what needs to transition and potential incompatibilities (if any). Below is an example of an output:
*** diagnose the deployment ... ******************************************************************************* Diagnose ODSEE Server : host1:1389 ******************************************************************************* ** Plugins : No user plugins are defined, nothing particular to migrate ** Plugins : No subtree counter plugins are enabled, nothing particular to migrate ** Schema The schema was extended regarding the original delivery. The following schema should be added to the new OUD server attributeTypes : ( 2.16.840.1.113730.9999 NAME 'customAttributeType' DESC 'Oracle defined attribute type' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE X-ORIGIN ( 'Custom' 'user defined' ) ) ** Password Policy A compatible password policy is defined, nothing particular to migrate ** Naming context(s) available on the ODSEE server : o=migration No incompatibility has been detected for naming context o=migration ** Indexes Only default indexes are defined, nothing particular to migrate ** Encrypted attributes No encrypted attributes are defined, no action is required
To verify that your directory server data is compliant with OUD schema before importing the data:
Export the data to LDIF from your directory server. For information on exporting data to LDIF, see Section 4.2, "Step 1: Creating a Reference OUD Instance."
Run the ds2oud
command to diagnose the data. For example:
$ ds2oud --ldifDBFile odsee-data.ldif --userSchemaFile 99user.ldif
In this example odsee-data.ldif
is your directory server data exported to LDIF and 99user.ldif
is your customized directory server schema file. Below is an example of output during data diagnostic:
*** diagnose the data ... ******************************************************************************* * Diagnose ODSEE LDIF data file : odsee-data.ldif ******************************************************************************* Error validating data against OUD schema Entry : unknown org.opends.sdk.DecodeException: Entry uid=user2,ou=users,o=data read from LDIF starting at line 49 includes value "" for attribute description that is invalid according to the associated syntax: The operation attempted to assign a zero-length value to an attribute with the directory string syntax
Schema errors may be reported for the following reasons:
Default schema is different.
OUD has a more recent version of standard schema.
Attribute value syntax validation and containment rules validations.
Unsupported directory metadata. This includes role-based ACIs, Roles or Class of Services definitions currently not supported by OUD password policies as LDAP sub-entries. These sub-entries contain (O)DSEE specific extensions account-based resource limits that differ between (O)DSEE and OUD.
In the above cases, OUD provides the commands below to make schema constraints flexible and resolve those schema errors.
Structural objectclass
errors:
Structural objectclass
errors occur when your directory server data is rejected during an import. A common reason for this error is the structural object-class for the user entry. The user entry must have exactly one structural object-class. If the entry has zero or more than one, the entry will be rejected. Also, because your (O)DSEE directory server does not differentiate between the two object-class types, this kind of schema inconsistency is common. Use the following command to avoid this error:
dsconfig set-global-configuration-prop --set \ single-structural-objectclass-behavior:accept -n
Invalid attribute value errors:
Attribute values must conform to the attribute syntax defined in the schema. By default, attribute syntax checking is enabled in OUD. For example, an attribute with Boolean syntax can hold TRUE or FALSE values only. In addition, zero-length attribute values are rejected by OUD during an import. However it is possible to make this constraints flexible for the DirectoryString syntax by using this command:
dsconfig set-attribute-syntax-prop --syntax-name Directory\ String \ --set allow-zero-length-values:true -n
When you transition the directory user schema, the (O)DSEE schema extensions are automatically added to the OUD reference instance schema using the ds2oud
tool in migration mode.
Schema is migrated automatically using the ds2oud
tool. You must migrate the schema before you migrate the configuration or errors will be triggered during subsequent transition steps. The following command propagates the user schema from your (O)DSEE directory server to OUD and it can also be used to migrate the (O)DSEE schema to other OUD instances:
$ ds2oud --migrateUserSchema -h host1.example.com -p 1389 \ -D "cn=directory manager" -j pwdfile
To migrate the (O)DSEE schema to other OUD instances, you can also copy the content of the <OUD_INSTANCE>/OUD/config/schema
directory to the corresponding directory of the new OUD instance, then restart the OUD instance.
Note:
Although theds2oud --migrateUserSchema
command handles any extensions made on the (O)DSEE user schema, schema violations still may occur when you import your user data into OUD. This happens because, unlike user-defined schema, standard schema varies slightly between (O)DSEE and OUD. If schema violations occur during the import process, then you must create additional schema extensions which are likely suggested as a result of the (O)DSEE diagnosis process.During this step, the OUD reference instance is configured so that it can provide an LDAP service equivalent to (O)DSEE.
Most of the (O)DSEE directory configuration is migrated automatically using the ds2oud
tool in migration mode. Additional configuration elements that cannot be migrated automatically have been identified in Section 4.3, "Step 2: Using ds2oud
to Diagnose the (O)DSEE Directory Server, Configuration, Schema and Data."
Configuration commands generated automatically are kept in a batch file so that they can be reused to initialize other instances quickly. Oracle recommends that additional commands created manually, should also be added to that batch file.
Run the ds2oud
command to migrate the following configuration settings from your (O)DSEE directory server to OUD:
Naming contexts
Global configuration settings that are relevant for OUD
Size-limit
Look-through-limit
Idle-time-limit
Max-psearches
Bind-with-dn-require-password
Allidthresholds
Database indexes
Global default access controls
Supported built-in plug-ins
7-bit check
UID uniqueness plug-in
Referential integrity plug-in
Strong password policy check
To apply each of the above configuration settings to each OUD instance, you must run the ds2oud
command in batch mode. It will then generate a list of commands to be applied with dsconfig
. This is recommended to be able to complement changes and replay them easily on every target system.
To produce the administrative command batch file to transition the configuration, run the following command:
ds2oud --migrateConfiguration --odseeBindDN "cn=directory manager" --odseePort <ODSEE_PORT> --odseeBindPasswordFile <ODSEE_ADMIN_PASSWORD_FILE> --oudBindDN "cn=directory manager" --oudBindPasswordFile <OUD_ADMIN_PASSWORD_FILE1> --oudPort <OUD_LDAP_PORT1> --oudAdminPort <OUD_ADMIN_PORT1> --no-prompt --batchFile <COMMAND_BATCH_FILE>
By default, self-signed certificates are automatically generated when OUD instances are created. In some cases you might want to reuse the (O)DSEE server certificate for the new OUD instance, so that the transition is transparent for SSL clients. This, however, might require installation of the OUD instance on the same box as the (O)DSEE server depending on SSL certificate options used.
To reuse the SSL server certificate, do the following:
Export the directory server certificate to a PKCS12 file. In the following example, dsee.p12
is the PKCS12 filename.
dsadm export-cert -o dsee.p12 <instance_path> defaultCert
Note:
By default, the alias of the directory server cert is defaultCert. Use the appropriate alias in case you choose to use another value. You can find more information on exporting a directory server in the Administrator's Guide of Oracle Unified Directory.Copy the PKCS12 file to <OUD_INSTANCE>/config
.
Create a PIN file containing the PKCS12 file password such as dsee.p12.pin
in the <OUD_INSTANCE>/config
directory. The directory server certificate can be imported in the OUD instance in two different ways:
Configure a PKCS12 OUD keystore pointing to the file exported from your directory server.
Import the certificate to the default JKS OUD keystore.
To configure the OUD PKCS12 keystore run the following command:
dsconfig set-key-manager-provider-prop \ -provider-name PKCS12 \ -set key-store-file:config/dsee.p12 \ -set key-store-pin-file:config/dsee.p12.pin \ -set enabled:true \
In these code samples, when we use the dsconfig
command connectivity-related arguments such as ports and credentials are omitted for the sake of simplicity.
To configure the LDAPS connection run the following command:
dsconfig set-connection-handler-prop \ --handler-name LDAPS\ Connection\ Handler \ --set key-manager-provider:PKCS12 \
To import the certificate to the existing OUD JKS keystore, do the following:
Locate the JAVA_HOME of the JVM used by OUD. The version of the JVM used is displayed at startup in the OUD error log.
Run the following command to import the certificate:
JAVA_HOME/bin/keytool -v -importkeystore -srckeystore <Path to PKCS12 cert file exported from DSEE> -srcstoretype PKCS12 -destkeystore <OUD_INSTANCE_DIR>/OUD/config/keystore -deststoretype JKS
When prompted, specify the JKS PIN (available in <OUD_INSTANCE_DIR>/OUD/config/keystore.pin
) and the PKCS12 PIN you used to export the DSEE server certificate.
Verify that the import operation was successful.
To list the content of the OUD JKS keystore, use the following:
JAVA_HOME/bin/keytool -list -keystore <OUD_INSTANCE_DIR>/OUD/config/keystore
Enter keystore password:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains two entries:
defaultcert, Aug 29, 2013, PrivateKeyEntry, Certificate fingerprint (MD5): 10:63:DC:B5:6B:C8:F3:A0:6B:A7:23:9E:0B:EA:9C:30 server-cert, Aug 29, 2013, PrivateKeyEntry, Certificate fingerprint (MD5): BE:C9:F3:8A:49:98:96:15:EF:AC:B4:08:6F:76:FB:05
By default, the (O)DSEE directory server certificate alias is "defaultCert
", the OUD server certificate alias is "server-cert
" and Java automatically chooses the best certificate among those present in the keystore. If you want to force the use of one certificate, run this command:
dsconfig set-connection-handler-prop \ --handler-name LDAPS\ Connection\ Handler \ --set ssl-cert-nickname:defaultcert \
Use --decrypt-attr
option with dsconf export
to decrypt attributes.You must make sure that attributes are decrypted when exported to the LDIF file. Corresponding attribute encryption must be configured in OUD so that values are re-encrypted during import.
You can find instructions to configure encrypted attributes in OUD in the Administrator's Guide for Oracle Unified Directory.
You must change the OUD password storage scheme configuration if you are using either coexistence strategy, that is, Replication Gateway or DIP. This will ensure that the password storage scheme configured on the OUD side corresponds to an algorithm supported by (O)DSEE. Otherwise, users will not be able to log in anymore on the (O)DSEE side when the password is modified on the OUD side. In (O)DSEE, passwords are stored using some password encryption scheme, such as, SHA-1
. In OUD, this is similar but passwords are stored by default in SSHA512
.In OUD, password storage scheme is configured in password policies.
Configuration changes generated in Section 4.5.1, "Using the ds2oud Command to Migrate the Configuration Settings," can be applied to the OUD directory server instance with the following command:
dsconfig -h <oud hostname> -p <oud admin port> -D cn="directory manager" -w <admin password> \ -F command_batch_file -X -n
The -F
or --batchFilePath
option of the dsconfig
command enables you to specify a number of operations that are completed in a single command by consolidating those operations in a file. This can significantly improve performance and simplify configuration of other instances when several dsconfig
commands are required.
Additional configuration changes identified in Section 4.5.1.1, "Migrating SSL Certificates," need to be applied also.
Note:
Schema changes must always be applied before configuration changes. These configuration changes will have to be applied on each OUD instance deployed later. For more information see, Section 4.7.1, "Deploying The Replication Gateway,"Once the OUD reference instance is configured, it is loaded with actual (O)DSEE user data and directory metadata.
User data present in your directory server must first be exported to the LDIF format so that they can be reimported to OUD. Go to Section 4.3, "Step 2: Using ds2oud
to Diagnose the (O)DSEE Directory Server, Configuration, Schema and Data," for information on exporting to LDIF files.
The data to be exported depends on the chosen transition strategy. For example, if you are using the Direct Transition Strategy or the Transition Strategy Using DIP, replication metadata that accounts for a large volume of the data on the disk should be filtered out at export time. But for the Transition Strategy using Replication Gateway, replication metadata is needed.
If you are using the Direct Transition Strategy or the Transition Strategy Using DIP, run the dsconf
export command as shown in the following example to export the user data to LDIF:
$ dsconf export -no-repl --decrypt-attr \ -h host1.example.com -p 1389 \ dc=example,dc=com odsee-data.ldif
If you are using Transition Using Replication Gateway Strategy the replication metadata must be kept and adapted to OUD format. To export the user data to LDIF using this strategy, run the dsconf
export
command as shown in the following example:
$ dsconf export -f opends-export --decrypt-attr -h host1.example.com -p 1389 \ dc=example,dc=com odsee-data.ldif
Note:
The option-f opends-export
in the preceding command is only applicable for ODSEE 11g Release 1 (11.1.1.5 or later) since the data must be exported from the ODSEE 11g master which is required if you are using the Replication Gateway. Also note that encrypted data on the disk must be decrypted during export.The import-ldif
command is used to populate an OUD directory server backend with data read from an LDIF file. The following is an import-ldif
example:
import-ldif -b <your user data suffix> -n userRoot --excludeAttribute "nsds5replconflict" -l <path to LDIF file>
When you use the opends-export
option during transition, (O)DSEE-specific attributes might exist in some entries which will prevent these entries from being imported. For instance, nds5replconflict
might exist in the (O)DSEE data so it is imperative to filter this attribute during import to OUD using the following import option:
--excludeAttribute "nsds5replconflict"
Directory metadata transition depends on the transition strategy you have chosen to use. This may include access control information (ACI), collective attributes and LDAP sub entries.
For the Direct Transition Strategy: the directory metadata only needs to be adapted once.
For the Replication Gateway Strategy: directory metadata are replicated between the directory server and OUD. The directory metadata must be kept compatible on both sides. However, some metadata are different between the two environments, so additional schema extensions will be required to avoid errors or loss of data.
For the DIP Strategy: DIP should be configured to synchronize user data. The directory metadata is generally added manually on OUD. In some cases, DIP can be configured to synchronize the metadata.
Access to data is managed with access control instructions (ACIs) that specify the access rights of entries. ACIs can be stored as part of the user data or in the OUD configuration.
Global ACIs vs. ACIs in the data
Global ACIs apply to all entries in the directory. They are stored in the configuration. (O)DSEE and OUD global ACIs can differ without causing errors as they are not replicated.
The ds2oud
tool migrates the global ACIs to OUD global ACIs automatically.
ACIs that are stored as part of the data, are replicated.
Differences with Syntax
The roledn
keyword is currently not supported in OUD 11g Release 2. ACIs with the roledn
keyword cannot be imported into OUD because ACI syntax checking fails. Roles can be replaced by groups and the roledn
keyword can be replaced by groupdn
(See Roles and ACIs).
A new value for the targetscope
keyword, subordinate
, is introduced in OUD. This value is not supported by (O)DSEE so it must not be used in a two-way replication topology between (O)DSEE and OUD.
Behavioral Differences
In a few cases, evaluation of the same ACI differs between (O)DSEE and OUD. Since OUD grants less access by default than (O)DSEE, you will need to grant additional write access during the transition so that OUD behaves like (O)DSEE. In such cases, OUD ACI evaluation would be more inflexible than on the (O)DSEE side.
By default, OUD ACIs don't allow users to reset another user's password. With OUD, a privilege must be added to achieve behavior that is equivalent to that of (O)DSEE. Alternatively, it is possible to disable the privilege subsystem. For example, the command below allows the admin to reset user passwords in (O)DSEE (this type of password reset is refused by default in OUD):
ldapmodify -p <dsee port> -D "cn=directory manager"-w <admin password dn: dc=example,dc=com changetype: modify replace: aci aci: (targetattr = "*") (version 3.0;acl "Custom LDAP Administrator";allow (all)(userdn = "ldap:///uid=admin,dc=example,dc=com");)
With OUD, the following privilege below must be added to achieve the equivalent behavior:
dn: uid=admin,dc=example,dc=com changetype: modify add: ds-privilege-name ds-privilege-name: password-reset
Alternatively, the privilege subsystem can be disabled using the following command:
dsconfig set-global-configuration-prop -add disabled-privilege:password-reset
When (O)DSEE and OUD do not need to coexist in a replication topology, ACIs can be manually adapted, if needed, before importing them into OUD, as described previously.
When one-way replication is used, ACIs present in the data on (O)DSEE may have to be adapted manually before transition. Invalid ACIs will not be imported during replication initialization because of ACI syntax checking. ACIs updates on the (O)DSEE side might still be replicated to OUD but they will not be applied on the OUD side.
If you have incompatible ACIs, an alternate is to configure the Replication Gateway to filter out ACIs during replication. Each (O)DSEE ACI would be filtered out and the administrator would need to create the corresponding ACIs in OUD, either as part of the data or in the configuration.
For two-way replication between (O)DSEE and OUD, the same recommendations as for one-way replication applies. In addition, OUD-specific ACIs extensions must not be used in a mixed environment.
Note:
(O)DSEE and OUD ACIs are compatible except, in some cases, when (O)DSEE specific keywords asroleDN
are used.Class of Services definitions are stored as LDAP sub entries along with the user data.
Class of Services functionality is currently not supported in OUD. When replication is configured between (O)DSEE and OUD, CoS definitions are automatically filtered out by the Replication Gateway.
CoS can be replaced by the standard Collective Attributes mechanism or by Virtual Attributes. In a replicated topology, computed attributes are generated by CoS on the (O)DSEE side while the equivalent computation is achieved with Collective Attributes or Virtual attribute on the OUD side.
Collective attributes definitions are stored as LDAP sub entries along with the user data, which means that they are replicated. Collective attributes provide fine-grained scoping control through the generic sub-entry subtree specifications. Virtual attributes are stored in the OUD configuration and are not subject to replication. When two-way replication is enabled between (O)DSEE and OUD, you should use Virtual Attributes instead of Collective attributes because Collective Attributes definitions are replicated back to (O)DSEE.
If you specifically need to use Collective attributes (see Section 4.6.5.4, "Classic CoS" and Section 4.6.5.3, "Indirect CoS"), the (O)DSEE schema should be extended with the schema object that pertain to Collective Attributes. In this case, the LDAP sub entries will be present in (O)DSEE but they will be inactive. This means that they will not cause any attribute computation. The schema definition associated with the collectiveAttributeSubentry
and subentry
object classes (present in the OUD schema file 00-core.ldif
) and the associated attributes can be added to the (O)DSEE schema.
Note:
In (O)DSEE, CoS is often used in conjunction with roles and password policies. For example, they can be used to assign a custom password policy to a set of users. OUD provides new ways to assign password policies to user accounts. Therefore, in many cases, there are simple alternatives to CoS.(O)DSEE Class Of Service type is covered in detail in the following sections.
(O)DSEE Pointer CoS can be used to share a common attribute among a set of entries.
The following (O)DSEE Pointer CoS below automatically assigns a facsimiletelephonenumber
with a fixed value (+61245607890) to all entries located under ou=People,dc=example,dc=com
.
dn: cn=ZipTemplate,ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: extensibleobject objectclass: cosTemplate facsimiletelephonenumber: +61245607890 cosPriority: 0 dn: cn=pointerCoS,ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosPointerDefinition cosTemplateDn: cn=ZipTemplate,ou=People,dc=example,dc=com cosAttribute: facsimiletelephonenumber
The following OUD virtual attribute can be used to compute an equivalent attribute value: this example creates and enables a virtual attribute rule that adds a virtual fax number of +61245607890 to any user entry matching the objectclass=person
filter (unless there is already a fax number in the user entry):
dsconfig -h localhost -p 4444 -D "cn=directory manager" -j <password_file> -n \ create-virtual-attribute \ --type user-defined -name "Sydney Fax Number" \ --set attribute-type:facsimiletelephonenumber -set enabled:true \ --set value:+61245607890 -set filter:"(objectClass=person)"
Unlike virtual attributes, collective attributes are stored along with user data, so they are replicated across OUD instances.
The following collective attribute generates a facsimiletelephonenumber for entries in the sub-tree ou=people,dc=example,dc=com
dn: cn=People Preferred Language,dc=example,dc=com changetype: add objectClass: top objectClass: subentry objectClass: collectiveAttributeSubentry objectClass: extensibleObject cn: People fac simile number facsimiletelephonenumber;collective: +61245607890 subtreeSpecification: {base "ou=people", minimum 1} collectiveConflictBehavior: virtual-overrides-real
(O)DSEE Indirect CoS names an attribute in the cosIndirectSpecifier
attribute to locate the template specific to each target. The template entry for indirect CoS can be any entry in the directory, including other user entries. The following indirect CoS example uses the manager attribute of the target entry to identify the CoS template entry. The template entry is the manager's user entry. The manager's user entry contains the value of the attribute to generate. In this case, the value is that of the departmentNumber
attribute.
dn: cn=generateDeptNum,ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosIndirectDefinition cosIndirectSpecifier: manager cosAttribute: departmentNumber dn: cn=Carla Fuentes,ou=People,dc=example,dc=com objectclass: cosTemplate objectclass: person departmentNumber: 318842 cn: Carla Fuentes
Inherited collective attributes can be used to replace Indirect CoS. Like regular collective attributes, inherited collective attributes are defined using LDAP sub-entries within the directory tree where they are applicable. Inherited collective attributes are replicated across OUD instances. If two-way replication is used between (O)DSEE and OUD, the (O)DSEE schema should be extended with the Collective Attribute schema element as described in Section 4.6.5.1, "Collective vs. Virtual Attributes." The following inherited collective attribute is equivalent to the Indirect CoS definition described previously.
dn: cn=indirectCOS,dc=example,dc=com objectClass: top objectClass: subentry objectClass: inheritedCollectiveAttributeSubentry objectClass: inheritedFromDNCollectiveAttributeSubentry cn: indirectCOS subtreeSpecification: {base "ou=people"} inheritFromDNAttribute: manager inheritAttribute: departmentNumber
This example shows how to generate a postal address value with a classic CoS definition. The generated value is specified in a template entry that is located by a combination of the cosTemplateDN
in the CoS definition and the value of the cosSpecifier
attribute in the target entry. The following example creates the definition entry by using the cosClassicDefinition
object class:
dn: cn=classicCoS,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDn: ou=templates,ou=People,dc=example,dc=com cosSpecifier: building cosAttribute: postalAddress dn: cn=B07,ou=templates, ou=People,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: extensibleobject objectclass: cosTemplate postalAddres: 7 Old Oak Street, Anytown, CA 95054
With this CoS definition, target entries (the entries under ou=People,dc=example,dc=com
) that contain the building
attribute will automatically have the corresponding postal address. The CoS mechanism searches for a template entry that has the specifier attribute value in its RDN. In this example, if Babs Jensen is assigned to building B07, her postal address is generated.
Equivalent behavior can be achieved in OUD with inherited collective attributes as follow:
dn: cn=classicCOS,dc=example,dc=com objectClass: top objectClass: subentry objectClass: inheritedCollectiveAttributeSubentry objectClass: inheritedFromRDNCollectiveAttributeSubentry cn: classicCOS subtreeSpecification: {base "ou=people"} inheritFromBaseRDN: ou=templates inheritFromRDNAttribute: building inheritFromRDNType: cn inheritAttribute: postalAddress
This inherited collective attribute sub-entry applies to user entries under ou=people,dc=example,dc=com
. The subentry adds the postalAddress attribute inherited from the user entry whose DN is constructed from ou=templates, the Inherited collective attribute sub-entry root DN dc=example,dc=com
and the RDN cn value taken from applicable entry building attribute, if any.
Like regular collective attributes, inherited collective attributes are defined using LDAP sub-entries within the directory tree where they are applicable. They are replicated across OUD instances. If two-way replication is used between (O)DSEE and OUD, the (O)DSEE schema should be extended with the collective attribute schema element as described in the Section 4.6.5.1, "Collective vs. Virtual Attributes."
Non-standard (O)DSEE roles are currently not supported in OUD 11g Release 2 (11.1.2) and are usually replaced by standard OUD groups. Role definitions are filtered out by the Replication Gateway.
The steps required to transition (O)DSEE roles to OUD depend on the way in which the roles are exposed to external client applications. In many deployments, roles are not exposed to client applications, that is, applications do not make use of the nsRole
or nsRoleDN
attributes. Such roles can be replaced by either static or dynamic groups for ACIs and password policies.
The roledn
ACI keyword can be used to grant/deny access to data based on user role. For example, the following (O)DSEE ACI grants access to the user password attribute to users with 'Password Manager' role.
dn: ou=data,o=example.com aci: (targetattr="userPassword")(version 3.0; acl "PasswordManager";allow (read,search,compare,write) roledn = "ldap:///cn=Password_Manager_Role,ou=roles,dc=example,dc=com";
The roledn
keyword is not supported in OUD 11g Release 2 (11.1.2). This has the following implications:
ACIs with the roledn
keyword cannot be imported into OUD 11g Release 2 (11.2.2).
ACIs present in the (O)DSEE data will not be applied to OUD. These ACIs will be replicated to OUD but changes will not be applied because the ACI syntax does not work for OUD
Roles used in ACIs should be replaced by groups using the groupdn
keyword before transition. For OUD, the preceding ACI above can be rewritten as:
dn: ou=data,o=example.com aci: (targetattr="userPassword")(version 3.0; acl "PasswordManager";allow (read,search,compare,write) groupdn = "ldap:///cn=Password_Manager_Group,ou=group,dc=example,dc=com";
The group pointed to by the ACI can be either a static group or a dynamic group.
To migrate role-based ACIs to group-based ACIs before you transition to OUD, you must:
Define groups that correspond to the roles (using the same DN)
Rewrite ACIs on the (O)DSEE side before transitioning to OUD
Note:
Role-based ACIs present in the (O)DSEE configuration are not replicated, so they do not need to be rewritten.In many deployments, roles are used to assign custom password policies based on role membership. For example, users with the Admin role are subject to the Administrator password policy. In this use case, roles are used in conjunction with CoS to create the virtual attribute pwdPolicySubEntry
in every user entry pointing to the password policy that should be used.
In OUD, a password policy can be associated directly with members of a group by using a virtual attribute. The following example associates the adminPasswordPolicy
password policy with members of the administrator
group.
dsconfig create-virtual-attribute -name "PWPolicy for Admins" --type user-defined --set attribute-type:ds-pwp-password-policy-dn --set group-dn:cn=administrators,ou=groups,dc=example,dc=com --set conflict-behavior:real-overrides-virtual --set value:"cn=adminPasswordPolicy,ou=policies,ddc=example,dc=com"
Note:
Unlike CoS, the virtual attribute above that associates password policies with roles is not replicated across OUD instances.If you are using the Direct Transition Strategy or Transition Using DIP Strategy (the following is not compatible with the Transition Using Replication Gateway Strategy), use the nsRole
attribute in the target user's entry to determine whether the DN of the appropriate role is present when you need to determine whether a user is a member of a given role in an application. In this case, role functionality can be simulated by following steps:
Extend OUD schema with the nsRole
attribute definition (this schema is provided in the file 03-dsee-roles.ldif
)
Create static or dynamic groups to define role membership. You must reuse the role DNs when you create the groups so that the nsRole
attribute content is not impacted.
Create a new instance of the isMemberOf
virtual attribute to provide the nsRole
virtual attribute as follow:
dsconfig -h localhost -p 4444 -D "cn=directory manager" -j <password_file> -n \ create-virtual-attribute -type is-member-of -name nsRole -set \ attribute-type:nsRole -set enabled:true
Note:
Virtual attribute definitions are stored in the OUD configuration and thus are not replicated. They must be configured on every OUD instance.If the application alters membership by placing the name of the corresponding role in the nsRoleDN
virtual attribute in a user's entry, create a dynamic group for each role (you must reuse the role DN), and extend the group member
URL filter so that it takes into account the nsRoleDN
for group membership. In the following example, any user entry that contains a nsRoleDN
value of "cn=Test Role,ou=Roles,dc=example,dc=com
" also has that DN present in the nsRole
operational attribute.
dn: cn=Test Role,ou=Roles,dc=example,dc=com objectClass: top objectClass: groupOfURLs cn: Test Role memberURL: ldap:///dc=example,dc=com??sub?(nsRoleDN=\ cn=Test Role,ou=Roles,dc=example,dc=com)
If your application needs to create, modify or delete role entries (for example, an entry containing one of the subordinates of the nsRoleDefinition
object class), that functionality is currently not available in OUD.
In OUD, roles are replaced by groups. To use the corresponding groups securely, you must set access control instructions (ACIs) to protect appropriate attributes. With dynamic groups, you must protect the part of the filter that would prevent the user from being able to relinquish the filtered group by modifying an attribute. Users should not be allowed to add, delete, or modify the attribute used by the filtered groups. In the same way, if the value of the filter attribute is computed, all the attributes that can modify the value of the filter attribute must be protected.
The ds2oud
tool, provided with OUD, migrates the standard attributes of the default password policy only. See Table 4-1, "Password Extensions for (O)DSEE and OUD" for password policy mapping from (O)DSEE to OUD.
Custom password policies can be stored either in the data or in the OUD configuration and can be assigned to target users by mean of an attribute in the user entry or based on the position of the sub entry in the DIT. Selecting the best options is key for a successful password policy transition. Ease of use and impact on the OUD administration should be considered (for example, password policies as sub-entries are replicated across OUD instances, password policies in the configuration are not). In addition, not all combinations are possible in OUD 11g Release 2 (11.1.2)
The following options must be selected based on your deployment constraints:
Store custom password policies as sub entries or in the OUD configuration
Use attributes in user entries or use the sub entry sub tree specification to assign password policies
If an attribute in user entry is used to assign the password policy, use an explicit setting, virtual attributes or collective attributes to populate the attribute
Reuse or filter out (O)DSEE password policies during replication
The main decision criteria to be considered are:
Does the (O)DSEE custom password policy rely on specific extensions?
Is replication used with (O)DSEE one-way only?
Is the (O)DSEE custom password policy sub-entry position compatible with OUD?
Is password policy assignment based on group memberships?
The following is a summary of the differences between OUD and (O)DSEE password policies:
The (O)DSEE password policy definition consists of standard attributes (defined in the pwdPolicy
object class) and specific extensions (defined in the sunPwdPolicy
object class)
OUD password policies also rely on standard attributes (defined in the pwdPolicy
object class). However, (O)DSEE-specific extensions are currently not supported in OUD 11g Release 2: Such extensions are automatically filtered out during replication and must be replaced by OUD-specific extensions defined in the ds-cfg-password-policy
object class.
Manual Adaptations required to migrate these extensions are summarized in the table below:
Table 4-1 Password Extensions for (O)DSEE and OUD
(O)DSEE Extensions | OUD Extensions |
---|---|
PasswordStorageScheme |
default-password-storage-scheme |
PwdKeepLastAuthTime |
last-login-time-attribute, last-login-time-format |
PasswordRootDnMayByPassModsChecks |
skip-validation-for-administrators |
pwdIsLockoutPrioritized |
N/A |
PwdCheckQuality |
password-validator |
In addition to the global password policy, you can create custom password policies. In (O)DSEE, custom password policies are stored as part of the data, as LDAP sub entries.
In OUD, custom password policies can be stored as part of the data, as LDAP sub entries, or directly in the OUD configuration.
In OUD, password policies defined as LDAP sub entries must rely on standard attributes only (see above) and cannot contain any extensions. This restriction does not apply to password policies stored in the OUD configuration.
In (O)DSEE, a password policy is assigned to a user account based on the value of the pwdPolicySubEntry
attribute. The attribute value can be either stored physically in the user entry or dynamically populated with CoS based on criteria matched by the entry. The location of the password policy LDAP sub entry is not used to assign the policy to target users. The default password policy applies when the pwdPolicySubEntry
attribute is not present in a user entry.
In OUD, a password policy can be assigned to a user account in two ways:
By setting the attribute ds-pwp-password-policy-dn
, either explicitly or via a virtual or collective attribute, as in (O)DSEE
By creating the password policy sub-entry in the DIT so that all user entries are below the password policy entry and target user entries match the LDAP filter/ subtree specification present in the sub-entry. Sub-entry sub-tree specification is defined in RFC3672.
The following example corresponds to the first case: the password policy ServiceAccount
is assigned to members of the group group_FirstLoginPolicy
by creating a virtual attribute that populates the attribute ds-pwp-password-policy-dn
based on group membership:
dn: cn=group_FirstLoginPolicy,dc=example,dc=com objectClass: groupOfURLs MemberURL: ldap://ou=people,dc=example,dc=com??sub? (pwdReset=TRUE) cn:group_FirstLoginPolicy dsconfig create-virtual-attribute --name "PWPolicy to Admins" \ --type user-defined --set attribute-type:ds-pwp-password-policy-dn \ --set group-dn:cn=group_FirstLoginPolicy,dc=example,dc=com \ --set conflict-behavior:real-overrides-virtual \ --set value:"cn=ServiceAccount,ou=passwordPolicies,ou=config,dc=example,dc=com"
The following example corresponds to the second case: the policy FirstLoginPolicy
applies to users who are members of the group newbees in the subtree ou=people,dc=example,dc=com
.
dn: cn=FirstLoginPolicy,dc=example,dc=com objectClass: subentry Objectclass: pwdpolicy SubtreeSpecification: { specificationFilter "ismemberOf=cn=group_FirstLoginPolicy,dc=example,dc=com"} PwdMaxFailure: 2 PwdAttribute: userPassword cn:FirstLoginPolicy
Note:
The subtree specification as implemented in OUD is a super-set of the standard: OUD considers any well-formed LDAP filter as a valid value for thespecificationFilter
attribute. This is a very convenient way to assign password policies based on group membership as shown in the preceding example.Evaluation of custom password policies differs between (O)DSEE and OUD. In (O)DSEE, a custom password policy overrides the default password policy settings. With OUD, a custom password policy inherits from the default password policy: Properties not defined at the custom policy level are taken from the default password policy at the functional level (even if the attribute names do not correspond). These differences must be taken into account during transition.
When OUD and (O)DSEE coexist in a replicated topology, password policies should be kept as consistent as possible between the two environments, even when they are not replicated through the replication protocol. For example, if password validators differ, a password could be valid on one side and considered invalid on the other side, leading to inconsistencies.
If account lockout is enabled for a given set of entries on (O)DSEE and disabled on OUD (or the reverse), a password reset will not unlock the account on the other side.
In a replicated topology with global password policy and account lockout across the entire topology, the (O)DSEE servers that communicate directly with the Replication Gateway must run with the password policy in DS6mode
and the user entries must not contain data related to previous password policy mode. (This is not a must have if you don't need global password policy and when OUD and (O)DSEE can have its own password policy management.) Other (O)DSEE servers can run in compatibility mode, but such deployment is not the preferred one.
For more information about changing password policy modes, refer to the Administrator's Guide for Oracle Directory Enterprise Edition 11g.
The command dsconf get-server-prop pwd-compat-mode
can be used to retrieve the current password policy mode.By default, ODSEE 11g Release 2 uses the DS5-compatible
mode. You must switch to DS6-mode
before exporting data from (O)DSEE. To switch to DS6-mode
, you will need to first switch to the intermediate DS6-migration mode.
The process to switch to DS6-mode
and regenerate user entries is described in the "Password Policy Compatibility" section in the Administrator's Guide for Oracle Directory Server Enterprise Edition.You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Both (O)DSEE and OUD allow you to configure password policies to force the lockout of accounts after a specified number of failed bind attempts. In addition, it is possible to lock an account manually. The locked account remains locked until the account is activated.
Transition of account state (locked/unlocked) between (O)DSEE and OUD require specific settings. In (O)DSEE, manual account lock relies on Roles: Locked entries are assigned nsRoleDN=cn=nsManagedDisabledRole,dc=com role
. On OUD, manual account lock relies on the boolean attribute ds-pwp-account-disabled
. To automatically import a manually locked account from (O)DSEE to OUD, use the following steps:
Create a collective attribute on OUD to map the nsroledn:nsRoleDN=cn=nsManagedDisabledRole to ds-pwp-account-disabled
: true
ldapmodify -a dn: cn=ManagedDisabledAttribute,<dc=example> objectClass: top objectClass: subentry objectClass: collectiveAttributeSubentry objectClass: extensibleObject cn: ManagedDisabledAttribute ds-pwp-account-disabled;collective: true subtreeSpecification: {specificationFilter "nsRoleDN=cn=nsManagedDisabledRole,dc=com"}
Extend the OUD schema with the nsroledn
operational attribute:
ldapmodify dn: cn=schema changetype: modify add: attributeTypes attributeTypes: ( 2.16.840.1.113730.3.1.575 NAME 'nsRoleDN' DESC 'Sun ONE defined attribute type' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 USAGE directoryOperation X-DS-USE 'internal' X-ORIGIN 'Sun ONE Directory Server' )
One-way (O)DSEE->OUD) replication of locked account require changes in the Replication Gateway configuration: By default, the nsroledn
attribute is not replicated and is filtered out by the Replication Gateway. This filtering rule must be removed by running the following command:
dsconfig set-plugin-prop --plugin-name Gateway\ Plugin --remove dsee-specific-attribute-types:nsroledn
Note:
thensroledn
attribute must not be used by any application on the OUD side. It is replicated to convey account state information only.Two-way replication of account lockout requires additional settings on OUD.
Extend (O)DSEE schema to add the ds-pwp-account-disabled
operational attribute:
ldapmodify dn: cn=schema changetype: modify add: attributeTypes @ attributeTypes: ( 1.3.6.1.4.1.26027.1.1.166 NAME 'ds-pwp-account-disabled' SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE USAGE directoryOperation X-ORIGIN 'OpenDS Directory Server' )
Create a filtered role on (O)DSEE to map account lockout from OUD:
ldapmodify -a dn: cn=OUD_DisabledRole,<dc=example> objectclass: top objectclass: LDAPsubentry objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsFilteredRoleDefinition cn: OUD_DisabledRole nsRoleFilter: (ds-pwp-account-disabled=true) Description: filtered role to map account lockout from OUD
Integrate the previous filtered role in the nested role used to disable the account on ODSEE:
ldapmodify dn: cn=nsDisabledRole,dc=com changetype: modify add: nsRoleDN nsRoleDN: cn=OUD_DisabledRole,dc=com
Note:
When an account is locked in (O)DSEE, the state information is replicated to OUD so the account is also locked in OUD. However, account unlock must be performed on both sides ((O)DSEE and OUD)An account can also be locked explicitly on (O)DSEE using the nsAccountLock
attribute.The equivalent attribute in OUD is ds-pwp-account-disabled
. Some client applications might rely on the nsAccountLock
attribute. In this case, the easiest way to address this is to declare nsAccountLock
as an attribute alias for ds-pwp-account-disabled
in the OUD schema as shown below:
attributeTypes: ( 1.3.6.1.4.1.26027.1.1.166 NAME ( 'ds-pwp-account-disabled' 'nsAccountLock' ) SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE USAGE directoryOperation X-ORIGIN 'OpenDS Directory Server' )
In (O)DSEE, the following limits can be associated with a password policy:
The look-through limit specifies the maximum number of entries examined for a search operation.
The size limit specifies the maximum number of entries returned in response to a search operation.
The time limit specifies the maximum time spent processing a search operation.
The idle time-out specifies the maximum time a client connection can remain idle before the connection is dropped.
More information on setting account limits refer to the "Setting Resource Limits For Each Client Account" section in the Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition. You can find that document in the Oracle Directory Server Enterprise Edition 11g Release 1 index page located at http://docs.oracle.com/cd/E19656-01/
In addition to that, these limits can be set for specific account/user entries: Some (O)DSEE entries may contain the following resource limit attributes: nsSizeLimit, nsTimeLimit, nsLookThroughLimit, nsIdleTimeout
.
Corresponding attributes on OUD are: ds-rlim-size-limit, ds-rlim-time-limit, ds-rlim-lookthrough-limit,ds-rlim-idle-time-limit
.
Account-based resource limits are not taken into account by ds2oud
and must be migrated manually.
When the Replication Gateway is used, the OUD schema (02-config.ldif)
must be modified so that each (O)DSEE attribute name related to resource limits is declared as an alias name for each corresponding OUD attribute.
In (O)DSEE, -1 is used to disable a resource limit. In OUD, 0 is used. One way to address this difference is to create a virtual attribute on OUD to override the content of the OUD attribute when the value of the (O)DSEE attribute is equal to -1. A virtual attribute must be created for the four attributes. Below are descriptions:
attributeTypes: ( 1.3.6.1.4.1.26027.1.1.166 NAME ( 'ds-pwp-account-disabled' 'nsAccountLock' ) SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE USAGE directoryOperation X-ORIGIN 'OpenDS Directory Server' )
dsconfig create-virtual-attribute --name "mapping nsTimeLimit " \ --type user-defined --set attribute-type:ds-rlim-time-limit \ --set filter:"(nsTimeLimit=-1)" \ --set conflict-behavior:virtual-overrides-real \ --set value:"0" \ --set enabled:true
dsconfig create-virtual-attribute --name "mapping nsLookthroughLimit " \ --type user-defined --set attribute-type:ds-rlim-lookthrough-limit \ --set filter:"(nsLookthroughLimit=-1)" \ --set conflict-behavior:virtual-overrides-real \ --set value:"0" \ --set enabled:true
dsconfig create-virtual-attribute --name "mapping nsIdleTimeout " \ --type user-defined --set attribute-type:ds-rlim-idle-time-limit \ --set filter:"(nsIdleTimeout=-1)" \ --set conflict-behavior:virtual-overrides-real \ --set value:"0" \ --set enabled:true
For the sake of performance, it is recommended to index the four attributes above for 'presence'.
Note:
With the settings above, (O)DSEE resource limit attribute names must always be used even on the OUD side. Use of the OUD attribute name cannot be used when (O)DSEE and OUD cohabit in the same replication topology.After completing Section 4.6, "Step 5: Transitioning User Data and Directory Metadata," selected applications can be validated against the OUD servers. If you have chosen:
"Coexistence Using the Replication Gateway," see Section 4.7.1, "Deploying The Replication Gateway," for instructions to deploy the Replication Gateway.
"Coexistence Using Oracle Directory Integration Platform (DIP)," see Section 4.7.2, "Deploying DIP," for instructions to deploy DIP.
"Direct Transition Strategy," continue to Step 7: Deploying Replicated Topology.
Below are additional components to configure the replication between (O)DSEE and OUD using the Replication Gateway.
Install and configure the Replication Gateway, as described in "Setting Up the Replication Gateway" section in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.
At this point you must configure a global administrator for replication. If you intend to connect this server to an existing replicated OUD topology at a later stage, use the same global administrator credentials that you have defined on the other OUD servers.
For example, assuming an existing OUD topology, your server layout prior to transition would be as follows:
Figure 4-1 Replication Server Topologies for (O)DSEE and OUD Prior to Transition
After transition, your server layout would be as follows:
Figure 4-2 Replication Server Topologies for (O)DSEE and OUD After Transition
Below are additional components to link between (O)DSEE and OUD using DIP. The procedures below configure the (O)DSEE server as the DIP backend directory so that your DIP-related metadata is no longer stored in OUD after you have deprovisioned your old directory server and DIP has been removed.
Choose the (O)DSEE master instance and the OUD directory server instance that will be synchronized. The OUD directory server must have an embedded replication server because the external changelog services is provided by replication servers.
Synchronize password storage schemes
Password storage schemes must be identical and compatible between (O)DSEE and OUD. To configure password storage schemes to enable synchronization refer to the "Default Password Policy" section in the Administrator's Guide for Oracle Unified Directory. You can find that document in the Oracle Unified Directory 11g Release 2 (11.1.2) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Create a directory suffix holding DIP metadata in (O)DSEE
Use the following command on DSEE 6.x (or higher) to create the suffix cn=products,cn=oraclecontext
to hold DIP metadata:
dsconf create-suffix -i -c -p $PORT -D "$ADMIN" -w "$PW_FILE" cn=products,cn=oraclecontext
For instructions for how to create the directory suffix for DSEE 5.2 see the Sun ONE Directory Server Administration Guide. That document is located in the Sun Java Enterprise System 2003Q4 index page located at
Enable changelog
Changelog must be enabled on the directory that will contain changes. Enable changelog on (O)DSEE with the following command:
dsconf set-server-prop -p $PORT -w "$PW_FILE" retro-cl-enabled:on
For two-way synchronization, external changelog must be enabled on OUD. By default, the external changelog is automatically enabled when the OUD instance is part of a replication topology. For testing purposes, set up a standalone OUD directory server instance and enable external changelog with the following command:
dsreplication enable-changelog --no-prompt --baseDN "dc=example,dc=com" --hostname "$HOST" --port $APORT --bindDN "$ADMIN" --adminPasswordFile "$PW_FILE" --trustAll
Install and configure DIP.
Install DIP in a Weblogic container.
For more information about on installing DIP in a Weblogic container, refer to the Oracle Directory Integration Platform Administrator's Guide. You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Configure DIP with the command below:
$ORACLE_HOME/bin/dipConfigurator setup -wlshost <hostname> -wlsport <admin_server_domain_Port> -wlsuser weblogic -ldaphost <dsee_host> -ldapport <dsee_port> -ldapuser "dsee_administrator" -metadatasuffix cn=products,cn=oraclecontext -isldapssl false
The <dsee_administrator>
, for example, cn=directory
manager must be granted read and write access to the DIP metadata suffix (cn=products,cn=oraclecontext
).
In the default password policy, the allow-pre-encoded
option must be 'true.' This will allow the <dsee_administrator>
to have access to write pre-encoded password.
For LDAP users, the following command will change the default password policy:
dsconfig set-password-policy-prop --policy-name Default\ Password\ Policy --set allow-pre-encoded-passwords: true
SSL users refer to the DIP Administrator's Guide to manage certificates
Create synchronization profiles.
Ensure that the oud_ldap_administrator, e.g. cn=directory manager has read and write access to the suffix to be synchronized. Also, when two-way synchronization is used, it must have read access on the OUD External changelog.
There are two ways to synchronize profiles: the command line and DIP graphical user interface (EM). The following is an example to synchronize profiles using the command line:
$ORACLE_HOME/bin/expressSyncSetup -h <dip_hostname> -p <dip_domain_port> -D weblogic -conDirType IPLANET -conDirUrl <OUD_host>:<oud_port> -conDirBindDN <oud_ldap_administrator> -conDirContainer <target_suffix> -backendDirContainer cn=products,cn=oraclecontext -pf <profile_name>
The command above creates one import file and one export file with the following naming convention:
If the profile name (-pf argument
) is profile1, expresSyncSetup
creates the two following profiles profile1Export
and profile1Import
.
To create synchronization profile using EM see refer to the Administrator's Guide for Oracle Directory Integration Platform.You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Use the DIP graphical user interface to update the list of attributes to be synchronized. This feature is described in the Administrator's Guide for Oracle Directory Integration Platform. You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Oracle recommends that you create 1-1 exact attribute mappings e.g. cn<->cn and that you create one extra mapping for each attribute alias e.g commonName->commonName
Configure ACIs
Additional directory ACIs must be created on the backend directory server for DIP to operate correctly.
The following command is an example of ACIs created on the backend directory on the suffix to be synchronized (dc=example,dc=com
):
ldapmodify -h <dsee_host> -p <dsee_port> -D "cn=Directory Manager" -w <password> <<EOF dn: dc=example,dc=com changetype: modify add: aci aci: (target="ldap:///dc=example,dc=com")(version 3.0; acl "Entry-level DIP permissions"; allow (all,proxy) groupdn="ldap:///cn=dipadmingrp,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext"; allow (all,proxy) groupdn="ldap:///cn=odipigroup,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext"; ) - add: aci aci: (targetattr="*")(version 3.0; acl "Attribute-level DIP permissions"; allow (all,proxy) groupdn="ldap:///cn=dipadmingrp,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext"; allow (all,proxy) groupdn="ldap:///cn=odipigroup,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext";) EOF
Export profile's entry must be added to the Export group:
ldapmodify -h <dsee_host> -p <dsee_port> -D "cn=Directory Manager" -w <password> <<EOF dn: cn=odipegroup,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext changetype: modify add: uniqueMember uniqueMember: orclodipagentname=profile1Export,cn=subscriber profile,cn=changelog subscriber,cn=directory integration platform,cn=products,cn=oraclecontext EOF
Note that the profile name (profile1Export
in the example) is part of the DN of the new member
When two-ways synchronization is used, the Import profile's entry must be added to the Import group:
ldapmodify -h <dsee_host> -p <dsee_port> -D "cn=Directory Manager" -w <password> <<EOF dn: cn=odipigroup,cn=DIPadmins,cn=Directory Integration Platform,cn=products,cn=oraclecontext changetype: modify add: uniqueMember uniqueMember: orclodipagentname=profile1Import,cn=subscriber profile,cn=changelog subscriber,cn=directory integration platform,cn=products,cn=oraclecontext EOF
In the example above, notice that the profile name (profile1Export
in the example) is part of the DN of the new member.
Managing Directory Bootstrapping.
Bootstrapping refers to the initial transition of data between the (O)DSEE back-end directory and OUD. Because the synchronization process can handle the transition of data between an (O)DSEE and OUD, you are not required to perform directory bootstrapping. However, relying on the synchronization process to perform the initial transition will be a time-consuming process. For this reason, you should perform directory bootstrapping when you first deploy DIP.
There are two possibilities to initialize the two directory topologies:
Enable the synchronization so that DIP creates every (O)DSEE entry to OUD.
Export the content of the (O)DSEE directory to an LDIF file, then import the content to OUD and configure DIP to use the (O)DSEE changelog.
The first solution is simpler but it is much slower than with the Direct Transition Strategy which uses this procedure.
To use the first solution you must:
Enable the synchronization profiles
Run the following commands:
$ORACLE_HOME/bin/syncProfileBootstrap -h <dip_host> -p <dip_domain_port> -D weblogic -pf profile1Import $ORACLE_HOME/bin/syncProfileBootstrap -h <dip_host> -p <dip_domain_port> -D weblogic -pf profile1Export
Directory Boostrapping is described in the Administrator's Guide for Oracle Directory Integration Platform. You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
To use the LDIF bootstrapping:
Use the following command to export entries from DSEE to data.ldif
file without the replication metadata and with the backend server in off-line mode:
$ dsconf export --no-repl -h host -p port suffix-DN LDIF-file
Retrieve the change number of the last update applied before the export began. To do so, start the export procedure then write down the time and convert it in Generalized Time in YYYYMMDDHHMMSSZ format: An example of a time stamp in a generalized time format is 20130508200557Z, which specifies a time (in the UTC time zone) of 8:05:57 PM on May 28, 2013.
Restart the (O)DSEE server (if needed) after the export has completed.
Run the following search command:
ldapsearch -p <dsee_port> -D <dsee_admin> -w <password> -b "cn=changelog" "changetime>= <timeStamp>" changeNumber
Note the value of the smallest changeNumber value returned by doing the following:
bash-3.2$ ./ldapsearch -p PORT -h DSEE HOSTNAME -D "cn=directory manager" -w PASSWORD -b "cn=changelog" "changetime>=20130508200557Z" changeNumber dn: changenumber=16747773,cn=changelog changeNumber: 16747773 dn: changenumber=167477734,cn=changelog changeNumber: 167477734 dn: changenumber=1674777345,cn=changelog changeNumber: 1674777345
Use the DIP management console (EM) as described in the "Administering Oracle Directory Integration Platform" section in the Administrator's Guide for Oracle Directory Integration Platform.
You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Or you can use the manageSyncProfiles
updatechgnum
command to start synchronization to update the last change number parameters of the DIP synchronization export profile with the above value. The manageSyncProfiles
updatechgnum
command is described in the "Syntax for manageSyncProfiles"
section of the Administrator's Guide for Directory Integration Platform.
You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Enable the DIP synchronization profiles using GUI or CLI as described in the "Enabling and Disabling Synchronization Profiles" section of the Administrator's Guide for Directory Integration Platform.
You can access that document in the Oracle Fusion Middleware 11g Release 1 (11.1.1.7) library located at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Synchronization will now begin based on the changelog.
Once the OUD reference instance is initialized, most of the transition work is completed.
Additional instances are created and initialized with the batch procedure identified in Section 4.5, "Step 4: Transitioning Directory Configuration." Replication is then enabled between OUD instances.
More information is located at: Administrator's Guide for Oracle Unified Directory, and Installation Guide for Oracle Unified Directory.
Once a reference OUD server has been configured and loaded with data from (O)DSEE as indicated in: "Step 1: Creating a Reference OUD Instance," "Step 2: Using ds2oud
to Diagnose the (O)DSEE Directory Server, Configuration, Schema and Data," "Step 3: Transitioning Directory Schema," "Step 4: Transitioning Directory Configuration", additional instances can be set up in the replicated environment. This step covers:
Configuring an OUD Replica
Deploying Topology
Initializing Data
These steps are required for every strategy.
As a reminder, (O)DSEE makes the distinction between three types of replicas:
A master replica is a read-write database that contains a master copy of the directory data.
A consumer replica is a read-only database that contains a copy of the information held in a master replica.
A hub replica is a read-only database, like a consumer replica, but stored on a directory server that supplies one or more consumer replicas.
For more information on (O)DSEE replicas, refer to the "Introduction to Replication" section in the Oracle Directory Server Enterprise Edition Reference. That document can be found in the Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.5) library at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
The OUD replication model is a multi-master model. In other words, all directory server replicas in a replicated topology can process both read and write operations.
Since the release of DSEE 6.x we have recommended multi-master replica with typical deployments which eliminated the need for consumer and hub replicas.
In most deployments, using read-only replica is not needed for performance reason and should only be done if the applications require it. In this case it is achieved by configuring the writability mode of the backend. However, you can configure an OUD directory server to be read-only, in which case add, modify, and delete operations from LDAP clients are rejected on this server and a referral is returned containing pointers to others (read-write) servers within the replicated topology.
Configuring an OUD Read-Write Replica
Cascaded Replication vs. Centralized Replication Model
In (O)DSEE, hub replicas are introduced with cascaded replication to make the replication protocol operate better. Cascading replication is useful in the following scenarios:
When there are a lot of consumers.
Because the masters in a replication topology handle all update traffic, it could put them under a heavy load to support replication traffic to the consumers. You can off-load replication traffic to several hubs that can each service replication updates to a subset of the consumers.
To reduce connection costs by using a local hub in geographically distributed environments.
In OUD, hub replicas do not exist. Replication is built around a centralized publish-subscribe architecture. Each directory server communicates with a central service, and uses the central service to publish its own changes and to receive notification about changes on other directory servers. This central service is called the replication service. OUD read-write masters are the default so in most cases they are deployed.
The replication service can be made highly available by using multiple server instances running on multiple hosts. Within the replication architecture, a server instance that provides the replication service is called a replication server. A server instance that provides the directory service is called a directory server.
In a small topology (up to four directory servers) it makes sense to configure each server to function as both a directory server and a replication server. In a large topology (more than twenty directory servers) it is advisable to separate the directory server and replication server instances into separate JVMs, and to limit the number of replication servers.
Between these two extremes, you can decide on the configuration that works best for your requirements. Having all servers functioning as both directory servers and replication servers is generally a simpler topology and easier to administer. Separating the directory servers and replication servers lowers the disk requirements of the directory server instances because they do not need to store a replication change log.
In large topologies with several directory servers and several replication servers, it is more efficient to spread the directory servers out across the replication servers in a predefined manner. This is particularly important if the replication servers are running on different types of machines with different capabilities. If the estimated performance of the machines differs significantly from one replication server to another, it is useful to balance the load on the replication servers according to their power.
You must understand the replication concepts of OUD because they are different than those of (O)DSEE. For more information about configuring Replication Servers and Load-balancing, refer to the "Replication Server Load Balancing" section in the Administrator's Guide of Oracle Unified Directory. That document can be can be found in the Oracle Unified Directory 11g Release 2 (11.1.2) library at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Configuring an OUD Read-Only Replica
This example assumes a replication configuration with replication servers on two hosts: host1 and host2. The example makes the directory server on host2 a read-only replica and uses the dsconfig
command which accesses the server configuration using the administration connector.
For more information on configuring an OUD read-only replica, see the "Managing Administration Traffic to the Server" section in the Administrator's Guide for Oracle Unified Directory. That document can be found in the Oracle Unified Directory 11g Release 2 (11.1.2) library at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
To configure OUD as a read-only replica use the dsconfig
command to set the writability-mode of host2:
$ dsconfig -h host2 -p 4444 -D "cn=Directory Manager" -j <password_file> -X -n \ set-global-configuration-prop --set writability-mode:internal-only
A writability mode of internal-only means that replication operations are processed on the server, but the server is not writable directly by LDAP client applications.
To create new OUD instances and enable replication between them do the following:
Create an OUD instance. For instructions for setting up a directory server refer to: the Installation Guide of Oracle Unified Directory.
Configure each OUD instance by applying the configuration changes identified in Section 4.5, "Step 4: Transitioning Directory Configuration," and for the additional configuration changes that might have been identified while importing the data, see: Section 4.6, "Step 5: Transitioning User Data and Directory Metadata."
Run the dsreplication
command to enable replication between OUD instances. The dsreplication
command is described in the "To Enable Replication Between Two Servers" section of the Administrator's Guide for Oracle Unified Directory. That document can be found in the Oracle Unified Directory 11g Release 2 (11.1.2) at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Deploying servers in a replicated topology is described in the "Configuring Data Replication With dsreplication" section in the Administrator's Guide for Oracle Unified Directory. That document can be found in the Oracle Unified Directory 11g Release 2 (11.1.2) at http://www.oracle.com/technetwork/middleware/id-mgmt/documentation/index.html
Once an OUD server is loaded with (O)DSEE data, you can either import the same file on every other OUD instance or use binary copy or initialize a replicated server with the data from another replicated server as described in the Administrator's Guide of Oracle Unified Directory.
Initialize OUD with (O)DSEE Data
Once you have set up the replication topology, you will need to initialize it with fresh data. There are four different options for every strategy to initialize the OUD instance with the (O)DSEE data already contained in the reference instance.
If you are using the Replication Gateway Strategy, you must ensure that the OUD reference instance is loaded with (O)DSEE data that was exported before the (O)DSEE replication purge delay configured on (O)DSEE.
The four options are:
Run the dsreplication
command to initialize each empty OUD instance. This procedure in described in section "26.1.2" of the Administrator's Guide of Oracle Unified Directory.
Initialize each OUD instance at the same time. This procedure is describe in Section 26.1.3 of the Administrator's Guide of Oracle Unified Directory.
Perform a binary copy of the database files from the reference OUD to each OUD instance. This procedure is described in Section 26.4.3 of the Administrator's Guide of Oracle Unified Directory.
Export entries from the reference OUD and reimported them into each empty OUD instance.
Coexistence between the two environments is kept until the application testing is complete.
This procedure depends on the architecture. Redirection may involve the reconfiguration of the software or hardware load-balancers, LDAP proxy servers, modification of the Domain Name Systems (DNS), or use of IP impersonation.
When all the applications have been redirected to OUD and validated, the Replication Gateway(s) and companion (O)DSEE server can be deprovisioned.
Once the Replication Gateway is no longer in use, it can be stopped and then uninstalled and the same is true for the (O)DSEE side.
Note:
After performing Section 4.10, "Step 9: Stopping Coexistence," your transition to OUD is complete. If you encounter problems during your transition, contact your Oracle support representative. For more information, go to the My Oracle Support web site located athttps://support.oracle.com