23 Configuring Integration Using the Proxy

This chapter describes how to configure the server elements that are specific to a proxy instance.

Note:

If you configure a load balancing or distribution topology while setting up a proxy instance, then many of these elements are automatically configured.

This chapter includes the following sections:

• Section 23.1, "Retrieving All Attribute Values from an Active Directory Server"

• Section 23.2, "Integrating with Enterprise User Security Databases"

• Section 23.3, "Updating User Passwords Stored in Active Directory"

• Section 23.4, "Configuring Pass-Through Authentication"

• Section 23.5, "Configuring Oracle Unified Directory Plug-Ins"

• Section 23.6, "Configuring a Proxy Instance to Monitor Back-End Servers"

• Section 23.7, "Configuring Global Indexes Using the Command Line"

• Section 23.8, "Configuring Virtual ACIs"

Note:

In some cases, you can choose to configure integration using dsconfig or Oracle Directory Services Manager (ODSM).

• For information about using the dsconfig command, see Section 17.1, "Managing the Server Configuration Using dsconfig."

• For information about using ODSM, see Chapter 16, "Accessing Oracle Unified Directory Using ODSM."

23.1 Retrieving All Attribute Values from an Active Directory Server

Oracle Unified Directory supports Microsoft Active Directory paging, which enables you to retrieve a complete range of attribute values from the Microsoft Active Directory server.

This section describes how to configure Microsoft Active Directory paging as a workflow element that is relevant only if the leaf of the workflow element chain is connected to an Active Directory server. It also describes how to configure an optional list of attributes to reduce the processing of scanning attributes to detect the range option.

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

The topics in this section include:

• Section 23.1.1, "Configuring Active Directory Paging Workflow Elements"

• Section 23.1.2, "Scanning Specific Attributes Returned by an Active Directory"

Note:

For more information about Microsoft Active Directory paging, see Section 12.4.1, "Retrieving All Attribute Values from an Active Directory Server."

23.1.1 Configuring Active Directory Paging Workflow Elements

Use the following example as a basis for configuring an Active Directory paging workflow element. This example creates an Active Directory paging workflow element named ad-paging-we1 that points to the LDAP proxy workflow, proxy-we1.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-workflow-element --element-name ad-paging-we1 --type ad-paging \
  --set next-workflow-element:proxy-we1 --set enabled:true

23.1.2 Scanning Specific Attributes Returned by an Active Directory

To improve efficiency, you can configure the Active Directory paging workflow element to scan only specific attributes by setting the multi-valued handled-attributes property of the workflow element. You can add as many values for this property as required.

By default all attributes are scanned. This can have a direct impact on performance. To reduce the performance impact, list only the attributes that need to be scanned as values of the handled-attributes property.

The following example modifies the workflow element created in the previous example to scan only for the memberOf attribute:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-workflow-element-prop --element-name ad-paging-we1 \
  --set handled-attributes:memberOf

23.2 Integrating with Enterprise User Security Databases

You can integrate Oracle Unified Directory and Enterprise User Security to leverage user identities stored in an LDAP-compliant directory service without any additional synchronization.

When integrated with Enterprise User Security, Oracle Unified Directory supports the following:

• Microsoft Active Directory

• Novell eDirectory

• Oracle Unified Directory

• Oracle Directory Server Enterprise Edition

For more information about Oracle Enterprise User Security, see the Oracle Database Enterprise User Security Administrator's Guide. For detailed instructions on configuring Oracle Unified Directory and Enterprise User Security to work together, see Chapter 31, "Integrating Oracle Unified Directory with Oracle Enterprise User Security."

23.3 Updating User Passwords Stored in Active Directory

The Ad Password workflow element enables Oracle Unified Directory LDAP client applications to update user passwords stored in Microsoft Active Directory and Active Directory Lightweight Directory Services (AD LDS) using the LDAP protocol.

For an overview of the Ad Password workflow element, see Section 12.4.3, "Enabling LDAP Clients to Update User Passwords Stored in Active Directory."

The following sections describe how to configure an Ad Password workflow element and its required components:

• Section 23.3.1, "Setting Up an Oracle Unified Directory Proxy Server"

• Section 23.3.2, "Creating and Configuring an Ad Password Workflow Element"

• Section 23.3.3, "Creating a Workflow for the Ad Password Workflow Element"

• Section 23.3.4, "Adding the Workflow to a Network Group"

Note:

The examples in this section uses the dsconfig command-line utility to create and configure the Ad Password workflow element and its required components. The descriptions of these examples mention key options and properties you must set.

For the description of all dsconfig subcommands and options, see Appendix A.

23.3.1 Setting Up an Oracle Unified Directory Proxy Server

The Ad Password workflow element requires an Oracle Unified Directory proxy server as the interface between LDAP clients and the Active Directory or AD LDS server.

The example in this section applies to both use cases described in Section 23.3.2, "Creating and Configuring an Ad Password Workflow Element."

To setup a proxy server instance using command-line tools on a UNIX or Linux system:

1. Ensure that your JAVA_HOME environment variable is set to a supported JVM installation (JRE 7 or JDK 7).

2. Run the oud-proxy-setup script to set up the proxy server instance:

   $ export INSTANCE_NAME=ad-oud-proxy-instance
   $ OUD_HOME/oud-proxy-setup --cli -p oud-port --adminConnectorPort admin-port
   -D "cn=Directory Manager" -j password-file
   

   In this example:

   • ad-oud-proxy-instance is the proxy instance directory name. This example sets the INSTANCE_NAME environment variable to this directory before running the oud-proxy-setup script.

   • oud-port is the LDAP port used to access the proxy server instance.

   • admin-port is the administration port.

   • password-file contains the administrator password.

On Windows systems, run the oud-proxy-setup.bat script.

For more information, see "Setting Up Oracle Unified Directory as a Proxy Server" in the Installing Oracle Unified Directory.

23.3.2 Creating and Configuring an Ad Password Workflow Element

When you create and configure an Ad Password workflow element and its supporting components, you have two choices:

• SSL is Required for Only Password Modifications

  For this use case, you must define the Ad Password workflow element with both the secure-proxy-workflow-element and next-workflow-element properties. The secure-proxy-workflow-element must use an LDAP server extension configured with remote-ldap-server-ssl-policy set to always.

  In this use case, operations to modify a password will be routed to the secure-proxy-workflow-element and will take place over SSL. Operations not related to password modifications will be routed to the next-workflow-element and will take place over a non-SSL connection.

  See Section 23.3.2.1, "Configuring an Ad Password Workflow Element When SSL is Required for Only Password Modifications."

• SSL is Required for All LDAP Operations

  For this use case, your proxy LDAP workflow element must point to an LDAP server extension that always uses SSL (remote-ldap-server-ssl-policy set to always). You can define the Ad Password workflow element with only a next-workflow-element property. All operations will then be routed to the next-workflow-element and will take place over SSL.

  See Section 23.3.2.2, "Configuring an Ad Password Workflow Element When SSL is Required for All LDAP Operations."

23.3.2.1 Configuring an Ad Password Workflow Element When SSL is Required for Only Password Modifications

The following tasks create and configure an Ad Password workflow element and its required components when an SSL connection to the Active Directory or AD LDS server is required only for LDAP operations that perform password modifications. Other LDAP operations are performed over a non-SSL connection.

These tasks include:

• Section 23.3.2.1.1, "Creating the LDAP Server Extensions"

• Section 23.3.2.1.2, "Creating the Proxy LDAP Workflow Elements"

• Section 23.3.2.1.3, "Creating an Ad Password Workflow Element"

23.3.2.1.1 Creating the LDAP Server Extensions

This use case requires two LDAP server extensions to communicate with the remote Active Directory or AD LDS server:

• An LDAP server extension for LDAP operations that do not require an SSL connection.

  and

• An LDAP server extension for LDAP operations that require an SSL connection.

LDAP Server Extension for Non-SSL Connections

To create an LDAP server extension that does not require an SSL connection from the LDAP clients to the Active Directory or AD LDS server:

$ dsconfig create-extension \
  --set enabled:true \
  --set remote-ldap-server-address:adserver.example.com \
  --set remote-ldap-server-port:389 \
  --set remote-ldap-server-ssl-port:636 \
  --type ldap-server \
  --extension-name adserver \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• remote-ldap-server-ssl-policy is not set in this command, so the default value of never specifies a non-SSL connection.

• extension-name is set to adserver for a non-SSL connection.

• enabled must be set to true to enable the LDAP server extension for use in the server.

LDAP Server Extension for SSL Connections

To create an LDAP server extension that requires an SSL connection from the LDAP clients to the Active Directory or AD LDS server:

$ dsconfig create-extension \
  --set enabled:true \
  --set remote-ldap-server-address:adserver.example.com \
  --set remote-ldap-server-ssl-policy:always \
  --set remote-ldap-server-port:389 \
  --set remote-ldap-server-ssl-port:636 \
  --set ssl-trust-all:true \
  --type ldap-server \
  --extension-name adsecureserver \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• remote-ldap-server-ssl-policy is set to always, so an SSL connection is always used to access the Active Directory or AD LDS server

• extension-name is set to adsecureserver to indicate an SSL connection.

• enabled must be set to true to enable the LDAP server extension for use in the server.

23.3.2.1.2 Creating the Proxy LDAP Workflow Elements

This use case requires two proxy LDAP workflow elements to communicate with the remote Active Directory or AD LDS server:

• A proxy LDAP workflow element for LDAP operations that do not require an SSL connection to the Active Directory or AD LDS server.

  and

• A secure proxy LDAP workflow element for LDAP operations that require an SSL connection to the Active Directory or AD LDS server.

Proxy LDAP Workflow Element for Non-SSL Connections

To create a proxy LDAP workflow element that does not require an SSL connection from the LDAP clients to the Active Directory or AD LDS server:

$ dsconfig create-workflow-element \
  --set client-cred-mode:use-client-identity \
  --set enabled:true \
  --set ldap-server-extension:adserver \
  --type proxy-ldap \
  --element-name adproxy \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• client-cred-mode is set to the use-client-identity bind mode, which specifies that the proxy will connect to the Active Directory or AD LDS server with the same credentials used by the client to connect to the proxy.

• element-name specifies the name of the proxy LDAP workflow element as adproxy.

• ldap-server-extension specifies the name of the LDAP server extension as adserver.

• enabled must be set to true to enable the Ad Password workflow element for use in the server.

Proxy LDAP Workflow Element for SSL Connections

To create a secure proxy LDAP workflow element that uses an SSL connection from the LDAP clients to the Active Directory or AD LDS server:

$ dsconfig create-workflow-element \
  --set client-cred-mode:use-client-identity \
  --set enabled:true \
  --set ldap-server-extension:adsecureserver \
  --type proxy-ldap \
  --element-name adsecureproxy \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• client-cred-mode is set to the use-client-identity bind mode, which specifies that the proxy will connect to the Active Directory or AD LDS server with the same credentials used by the client to connect to the proxy.

• element-name specifies the name of the secure proxy LDAP workflow element as adsecureproxy.

• ldap-server-extension specifies the name of the LDAP server extension as adsecureserver.

• enabled must be set to true to enable the proxy LDAP workflow element for use in the server.

23.3.2.1.3 Creating an Ad Password Workflow Element

This use case requires an Ad Password workflow element that can handle LDAP operations that support both SSL and non-SSL connections to the Active Directory or AD LDS server.

To create this Ad Password workflow element:

$ dsconfig create-workflow-element \
  --set enabled:true \
  --set next-workflow-element:adproxy \
  --set secure-proxy-workflow-element:adsecureproxy \
  --type ad-password \
  --element-name ADPasswordWFE \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• type must be ad-password.

• element-name specifies the workflow name as ADPasswordWFE.

• next-workflow-element routes LDAP operations to the proxy LDAP workflow element named adproxy, which routes operations over a non-SSL connection.

• secure-proxy-workflow-element routes LDAP operations to the proxy LDAP workflow element named adsecureproxy, which then routes operations over an SSL connection.

• enabled must be set to true to enable the Ad Password workflow element for use in the server.

23.3.2.2 Configuring an Ad Password Workflow Element When SSL is Required for All LDAP Operations

The following configuration tasks create and configure the components for an Ad Password workflow element when all LDAP operations between the LDAP clients and Active Directory or AD LDS server must be performed over an SSL connection.

These tasks include:

• Section 23.3.2.2.1, "Creating an LDAP Server Extension"

• Section 23.3.2.2.2, "Creating a Proxy LDAP Workflow Element"

• Section 23.3.2.2.3, "Creating an Ad Password Workflow Element"

23.3.2.2.1 Creating an LDAP Server Extension

The Ad Password workflow element requires an LDAP server extension to communicate with the remote Active Directory or AD LDS server.

To create an LDAP server extension that always uses an SSL connection:

$ dsconfig create-extension \
  --set enabled:true \
  --set remote-ldap-server-address:adserver.example.com \
  --set remote-ldap-server-port:389 \
  --set remote-ldap-server-ssl-port:636 \
  --set remote-ldap-server-ssl-policy:always \
  --set ssl-trust-all:true \
  --type ldap-server \
  --extension-name adsecureserver \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• type must be ldap-server.

• extension-name defines the name of the new extension as adsecureserver.

• remote-ldap-server-ssl-policy property is set to always, so that all connections made from the proxy to the remote Active Directory or AD LDS server will use SSL, regardless of how clients connect to the proxy server.

• enabled must be set to true to enable the LDAP server extension for use in the server.

23.3.2.2.2 Creating a Proxy LDAP Workflow Element

This use case requires a secure proxy LDAP workflow element to communicate with the remote Active Directory or AD LDS server over SSL.

To create a secure proxy LDAP workflow element:

$ dsconfig create-workflow-element \
  --set client-cred-mode:use-client-identity \
  --set enabled:true \
  --set ldap-server-extension:adsecureserver \
  --type proxy-ldap \
  --element-name adsecureproxy \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• type must be proxy-ldap.

• element-name specifies the name of the new proxy LDAP workflow element as adsecureproxy.

• ldap-server-extension is set to adsecureserver, which is the name of the LDAP server extension with the remote-ldap-server-ssl-policy property set to always.

• client-cred-mode is set to use-client-identity, which specifies that the proxy will connect to the Active Directory or AD LDS server with the same credentials used by the client to connect to the proxy.

• enabled must be set to true to enable the proxy LDAP workflow element for use in the server.

23.3.2.2.3 Creating an Ad Password Workflow Element

This use case requires an Ad Password workflow element that can handle LDAP operations that always require an SSL connection to the Active Directory or AD LDS server.

This Ad Password workflow element requires only the next-workflow-element property. All operations will take place over an SSL connection.

To create this Ad Password workflow element:

$ dsconfig create-workflow-element \
  --set enabled:true \
  --set next-workflow-element:adsecureproxy \
  --type ad-password \
  --element-name ADPasswordWFE \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• next-workflow-element property is set to the secure proxy LDAP workflow element named adsecureproxy.

• type must be ad-password.

• element-name is set to ADPasswordWFE.

• enabled must be set to true to enable the Ad Password workflow element for use in the server.

23.3.3 Creating a Workflow for the Ad Password Workflow Element

The Ad Password workflow element must be associated with a workflow. The following example applies to both use cases described in Section 23.3.2, "Creating and Configuring an Ad Password Workflow Element."

To create a workflow for the Ad Password workflow element:

$ dsconfig create-workflow \
  --set base-dn:dc=example,dc=com \
  --set enabled:true \
  --set workflow-element:ADPasswordWFE \
  --type generic \
  --workflow-name adworkflow \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

In this example:

• workflow-element is set to the Ad Password workflow element named ADPasswordWFE.

• workflow-name is set to adworkflow.

• enabled must be set to true to enable the Ad Password workflow element for use in the server.

23.3.4 Adding the Workflow to a Network Group

Network groups are the single entry point of client requests to Oracle Unified Directory. A workflow must be registered with at least one network group, although it can be attached to several network groups.

You must add the workflow from the previous task to either an existing network group or a new network group.

The following example applies to both use cases described in Section 23.3.2, "Creating and Configuring an Ad Password Workflow Element." It adds the adworkflow workflow to the default network group (network-group).

$ dsconfig set-network-group-prop \
  --group-name network-group \
  --add workflow:adworkflow \
  --hostname localhost \
  --port 4444 \
  --trustAll \
  --bindDN cn=directory\ manager \
  --bindPasswordFile pwd.txt \
  --no-prompt

23.4 Configuring Pass-Through Authentication

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

Note:

For more information about pass-through authentication, see Section 12.4.4, "Understanding Pass-Through Authentication."

To implement pass-through authentication, you must perform the following steps:

1. Review the following prerequisites and best practices information and then, if necessary, perform the prerequisite steps.

   • Section 23.4.1, "Prerequisites for Configuring Pass-Through Authentication"

   • Section 23.4.2, "Best Practices for Configuring Pass-Through Authentication."

2. Configure pass-through authentication.

   • If you are using dsconfig, see Section 23.4.3, "Configuring Pass-Through Authentication Using dsconfig."

   • If you are using ODSM, see Section 23.4.3, "Configuring Pass-Through Authentication Using dsconfig."

3. Create a workflow using the pass-through authentication workflow element or the Kerberos workflow element.

   • If your user entries are stored on a remote LDAP server, then see Section 23.4.3.1, "Configuring Pass-Through Authentication for Different Servers."

   • If your user entries are stored on a Kerberos server, then see Section 23.4.3.2, "Configuring Pass-Through Authentication for a Kerberos Server."

4. Insert the workflow created in Step 3 into an existing network group or a new network group.

23.4.1 Prerequisites for Configuring Pass-Through Authentication

Before attempting to implement pass-through authentication, read Section 12.4.4, "Understanding Pass-Through Authentication." In addition, you must keep the following steps in mind while configuring pass-through authentication:

1. Create or identify a workflow element for the Auth provider.

   • If the credentials are stored on a remote LDAP server, then you must create a LDAP server extension and a Proxy LDAP workflow element for this remote server, and then use this Proxy LDAP workflow element as auth-provider-workflow-element as described in Section 23.4.3.1, "Configuring Pass-Through Authentication for Different Servers."

     Keep in mind that you must configure remote-root-dn and remote-root-password parameters, and set the client-cred-mode=use-client-identity bind mode.

     For more information about how to create an LDAP server extension, see Section 20.2.1, "Configuring LDAP Server Extensions."

   • If the credentials are stored inside a Kerberos server, then you must create a Kerberos workflow element, and then use this Kerberos workflow element as auth-provider-workflow-element in step 1 as described in Section 23.4.3.2, "Configuring Pass-Through Authentication for a Kerberos Server."

2. Create or identify a workflow element for the User provider.

   • If the user entries are stored on a remote LDAP server, then you must create a LDAP server extension and a Proxy LDAP workflow element for this remote server, and then use this Proxy LDAP workflow element as user-provider-workflow-element as described in Section 23.4.3.1, "Configuring Pass-Through Authentication for Different Servers."

     Keep in mind that you must configure remote-root-dn and remote-root-password parameters.

     For more information about how to create an LDAP server extension, see Section 20.2.1, "Configuring LDAP Server Extensions."

   • If the user entries are stored locally, then you must create a Local Backend workflow element, and then use this Local Backend workflow element as user-provider-workflow-element as described in Section 23.4.3.1, "Configuring Pass-Through Authentication for Different Servers."

23.4.2 Best Practices for Configuring Pass-Through Authentication

Oracle Unified Directory recommends the following best practices to configure pass-through authentication:

• If you are using different suffixes for user-provider workflow element and authentication-provider workflow element, then it is recommended to define virtual ACIs to protect your data. Your virtual ACIs are defined using pta-suffix.

• If the authentication provider is a Kerberos workflow element, then you should not specify any join rule or authentication suffix.

• If the authentication provider is a Proxy workflow element, then you are required to configure a remote-root-dn.

• If the user provider is a Proxy workflow element, then you are required to configure a remote-root-dn. You must configure the proxy server carefully, because it performs silent bind.

23.4.3 Configuring Pass-Through Authentication Using dsconfig

This section describes how to configure pass-through authentication using the dsconfig command.

The following examples configure pass-through authentication with a remote LDAP server that stores the credentials with a base DN dc=auth,dc=com. The Oracle Unified Directory instance stores the user entries locally below the dc=user,dc=com suffix.

Here the remote LDAP server acts an Authentication Server, whereas Oracle Unified Directory acts as the User Server.

All the commands in the following procedures specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password file (-j). The examples use the -X option to trust all certificates.

This section contains the following topics:

• Section 23.4.3.1, "Configuring Pass-Through Authentication for Different Servers"

• Section 23.4.3.2, "Configuring Pass-Through Authentication for a Kerberos Server"

23.4.3.1 Configuring Pass-Through Authentication for Different Servers

To configure pass-through authentication for a remote LDAP server, perform the following steps:

1. Create a LDAP server extension for the LDAP server that stores the credentials.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" \
   -j pwd-file -X -n create-extension --extension-name authServer \
   --type ldap-server --set enabled:true \
   --set remote-ldap-server-address:authHostname \
   --set remote-ldap-server-port:1389 \
   

   For more information about how to create an LDAP server extension, see Section 20.2.1.4, "Creating an LDAP Server Extension."

2. Create a Proxy LDAP workflow element using the LDAP server extension that you have created in Step 1.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --element-name authProxy --type proxy-ldap \
   --set enabled:true --set client-cred-mode:use-client-identity \
   --set ldap-server-extension:authServer \
   --set remote-root-dn:cn=administrator,cn=users,dc=auth,dc=com \
   --set remote-root-password:********
   

   For more information about how to create a Proxy LDAP workflow element, see Section 23.3.2.1.2, "Creating the Proxy LDAP Workflow Elements."

3. Create a Local Backend workflow element to store the user entries locally, below the dc=user,dc=com suffix.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --element-name userWfe --type db-local-backend \
   --set enabled:true --set base-dn:"dc=user,dc=com"
   

4. Create the Pass-Through Authentication workflow element.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --element-name ptaWfe \
   --type pass-through-authentication --set enabled:true \
   --set auth-provider-workflow-element:authProxy \
   --set user-provider-workflow-element:userWfe \
   --set pta-auth-suffix:dc=auth,dc=com --set pta-suffix:dc=user,dc=com \
   --set pta-user-suffix:dc=user,dc=com
   

23.4.3.2 Configuring Pass-Through Authentication for a Kerberos Server

To configure pass-through authentication with kerberos workflow element, perform the following steps

1. Create a Kerberos Auth Provider workflow element.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --type kerberos-auth-provider \
   --element-name kerberosWfe --set enabled:true
   

2. Create a Local Backend workflow element to store the user entries locally, below the dc=user,dc=com suffix.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --element-name userWfe --type db-local-backend \
   --set enabled:true --set base-dn:dc=user,dc=com
   

3. Create a Pass-Through Authentication workflow element.

   dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
   create-workflow-element --element-name ptaWfe \
   --set auth-provider-workflow-element:kerberosWfe --set enabled:true \
   --set user-provider-workflow-element:userWfe --type pass-through-authentication
   

23.4.4 Configuring Pass-Through Authentication Using ODSM

For information about configuring a pass-through authentication workflow element using ODSM, see Section 17.3.4.1, "Creating a Workflow Element."

23.5 Configuring Oracle Unified Directory Plug-Ins

You can use the Oracle Unified Directory plug-in API to extend existing directory server functionality when you have a particular requirement and Oracle Unified Directory does not provide the necessary functionality to accommodate that requirement.

For example, you might configure a plug-in to customize LDAP operations or programmatically manipulate results.

Note:

• For detailed information about developing and deploying Oracle Unified Directory plug-ins, see the Oracle Fusion Middleware Developing Plug-Ins for Oracle Unified Directory.

• For more information about Oracle Unified Directory plug-ins, see Section 12.4.5, "Understanding Oracle Unified Directory Plug-Ins."

23.6 Configuring a Proxy Instance to Monitor Back-End Servers

The proxy server periodically performs health check to determine the status and in turn the availability of the host. You can configure the time interval between checks using the monitoring-check-interval property of ldap-server-extension instance.

The monitoring-check-interval property of proxy configuration against all back-end servers, defines the time internal (in milliseconds) between health checks scheduled by the proxy server.

You can set the monitoring-check-interval property using the dsconfig command as follows:

dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file --no-prompt\
set-extension-prop \
--extension-name proxy1 \
--set monitoring-check-interval:50000 \

23.7 Configuring Global Indexes Using the Command Line

Global indexes map entries to a specific distribution partition to speed up search and modify operations in distributed topologies. A global index maps entries based on a unique attribute, such as a phone number. Lists of global indexes are contained in a global index catalog. A proxy instance can contain one or more global index catalogs.

Note:

To configure and manage global indexes and global index catalogs, you must enable specific controls on the remote servers, particularly the LDAP Pre-Read Control and the CSN Control. For more information, see Appendix B, "Supported Controls and Operations."

This section contains the following topics:

• Section 23.7.1, "Configuring Global Index Catalogs Using gicadm"

• Section 23.7.2, "Replicating Global Index Catalogs"

• Section 23.7.3, "Configuring Controls Required by the Global Index Catalog with Oracle Unified Directory"

23.7.1 Configuring Global Index Catalogs Using gicadm

Global index catalogs are stored in a Berkeley database under INSTANCE_DIR/OUD/catalogs. To ensure high availability of a distributed topology, replication of global index catalogs is recommended. For more information, see Section 23.7.2, "Replicating Global Index Catalogs."

The gicadm command is located in the server instance directory:

• For UNIX: INSTANCE_DIR/OUD/bin/gicadm

• For Windows: INSTANCE_DIR\OUD\bat\gicadm.bat

For more information, see Appendix A, "gicadm."

The procedures in this section assume that the proxy is deployed in a distribution architecture and presume that you are using the default proxy administration port (4444). This section contains the following topics:

• Section 23.7.1.1, "Creating a Global Index Catalog Containing Global Indexes"

• Section 23.7.1.2, "Viewing Global Index Catalog Properties"

• Section 23.7.1.3, "Modifying the Global Index Catalog Properties"

• Section 23.7.1.4, "Modifying the Global Index Catalog Properties"

• Section 23.7.1.5, "Modifying Multi-Valued Global Index Catalog Properties"

• Section 23.7.1.6, "Resetting Global Index Catalog Properties to the Default Values"

• Section 23.7.1.7, "Viewing Global Index Properties"

• Section 23.7.1.8, "Importing Content into a Global Index Catalog"

• Section 23.7.1.9, "Exporting Contents of a Global Index Catalog to a Directory"

• Section 23.7.1.10, "Associating a Global Index Catalog With a Distribution Element"

• Section 23.7.1.11, "Disassociating a Global Index Catalog From a Distribution Element"

• Section 23.7.1.12, "Adding a Global Index to a Global Index Catalog"

• Section 23.7.1.13, "Removing a Global Index From a Global Index Catalog"

23.7.1.1 Creating a Global Index Catalog Containing Global Indexes

To create global indexes, you must first create global index catalogs, as described in the following procedure. This procedure describes how to create global index catalogs, create and add global indexes, and add data to the global indexes. You can add the data to your global indexes later, if you prefer.

Before you begin, the proxy must be deployed for distribution.

1. Use the gicadm command to create a global index catalog:

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
   create-catalog --catalogName sampleCatalog
   

   The catalog name must be unique.

2. Create and add at least one global index to the global index catalog.

   The following command creates a global index of telephoneNumber attribute values and adds that global index to the global index catalog that was created in the previous step.

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
     add-index --catalogName sampleCatalog --attributeName telephoneNumber
   

   You can use the add-index subcommand later to add additional global indexes to the global index catalog.

3. Associate the global index catalog to a distribution.

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
     associate --catalogName sampleCatalog \
     --distributionWorkflowElement myDistributionName
   

   For information about workflow elements, see Section 17.1.8, "Configuring Workflow Elements Using dsconfig." For information about distribution, see Section 22.1, "Configuring Distribution Using the dsconfig Command."

4. Use the split-ldif command to generate multiple files from one LDIF file.

   The split-ldif command separates the content of one LDIF file into several LDIF files based on the distribution algorithm configured with your proxy. It can also generate files that contain data to load in a global index. You should use split-ldif during global index initialization if the remote LDAP servers will contain data that must be indexed when you start your Directory service. If you plan to start without data in your directory, you can skip this step.

   For information on the split-ldif command, including examples on how to use the command to populate a global index with one or several indexed attributes, see Appendix A, "split-ldif."

5. Use the gicadm import command to import data into the global index.

   For more information, see Section 23.7.1.8, "Importing Content into a Global Index Catalog."

23.7.1.2 Viewing Global Index Catalog Properties

Global index catalog properties are related to global index catalog replication. To view a list of the global index catalog properties and an explanation of their use, see Section 23.7.1.3, "Modifying the Global Index Catalog Properties."

To view all the properties of a global index catalog, use the gicadm command with the get-catalog-prop subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  get-catalog-prop --catalogName sampleCatalog --property all

The output will be similar to the following.

Property   : Value(s)
-------------------:-------------------------------
replication-server : localhost:3390, localhost:4390
server-id          : 4247
window-size        : 100
heartbeat-interval : 1000
group-id           : 1

To view the value for a specific global index catalog property, specify the property.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  get-catalog-prop --catalogName sampleCatalog --property heartbeat-interval

23.7.1.3 Modifying the Global Index Catalog Properties

Global index properties are related to the replication of global index catalogs. The following global index catalog properties are available:

• replication-server: Lists the servers in the replication topology, in the format host:port. Do not use the set-catalog-prop command to modify this property. Instead, use the enable-replication command.

• server-id: Specifies a unique identifier for the global index within the global index catalog replication domain. Each instance within the same global index catalog replication domain must have a different server ID. An instance which is a member of multiple global index catalog replication domains may use the same server ID for each of its global index catalog replication domain configurations.

  Syntax: 1 <= INTEGER <= 65535 or text. This property should not be modified.

• window-size: Specifies the window size that the instance will use when communicating with replication servers. Default value is 100.

  Syntax: 0 <= INTEGER or text.

• heartbeat-interval: Specifies the heartbeat interval that the instance will use when communicating with replication servers. The instance expects a regular heartbeat from the replication server within the specified interval. If a heartbeat is not received within this interval, the instance closes its connection and connects to another replication server.

  Syntax: 100 ms <= DURATION (ms)

• group-id: The id associated with a specific replicated domain. This value defines the group id of the replicated domain. The replication system will preferably connect and send updates to replicate to a replication server with the same group id as itself.

  Syntax: 1 <= INTEGER <= 127

  Note:

  This property should not be modified.

23.7.1.4 Modifying the Global Index Catalog Properties

For a list of the global index catalog properties, see Section 23.7.1.3, "Modifying the Global Index Catalog Properties."

Use the gicadm command with the set-catalog-prop subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  set-catalog-prop --catalogName sampleCatalog --set property:value

For example, one of the properties that can be modified is the heartbeat interval. In this case, use:

--set heartbeat-interval:500

23.7.1.5 Modifying Multi-Valued Global Index Catalog Properties

For multi-valued global index or global index catalog properties, you can add or remove a value using the --add or --remove options.

For global index catalog, only the property replication-server can be multi-valued. For multi-valued global index properties, use the set-index-prop subcommand instead

1. To add a value, use the gicadm command with the set-catalog-prop subcommand.

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
     set-catalog-prop --catalogName sampleCatalog --add replication-server:hostname
   

2. To remove a value from a multi-valued property, use the gicadm command with the set-catalog-prop subcommand.

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
     set-catalog-prop --catalogName sampleCatalog \
     --remove replication-server:hostname
   

23.7.1.6 Resetting Global Index Catalog Properties to the Default Values

If you have modified any of the global index catalog properties and want to reset them to the default values, use the following procedure.

Use the gicadm command with the set-catalog-prop subcommand.

For example, to reset the heartbeat interval:

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  set-catalog-prop --catalogName sampleCatalog --reset heartbeat-interval

23.7.1.7 Viewing Global Index Properties

To view the properties of a global index, use the gicadm command with the get-index-prop subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  get-index-prop --catalogName sampleCatalog --attributeName telephoneNumber \
  --property all

The properties should be similar to the following:

Property Names                               : Property Values
---------------------------------------------:---------------------------------
global-index-deleted-entry-retention-timeout : 500
db-cleaner-min-utilization                   : 50
db-log-file-max                              : 10000000
db-checkpointer-bytes-interval               : 20000000
db-checkpointer-wakeup-interval              : 30
db-num-lock-tables                           : -
db-num-cleaner-threads                       : -
db-txn-no-sync                               : false
db-txn-write-no-sync                         : true
je-property                                  : -
db-directory                                 : catalogs
db-directory-permissions                     : 700
global-index-catalogs-shared-cache           : global-index-catalogs-shared-cac
global-index-attribute                       : telephoneNumber

Note:

Generally, these values should not be modified.

23.7.1.8 Importing Content into a Global Index Catalog

You can import the contents of a specific file into one or multiple global indexes in a global index catalog. You must specify the name of the catalog into which the content of the file is to be imported. You can filter the content of the file to data related to a particular index by optionally providing the attributeName parameter.

The data file to be imported can be created by executing the split-ldif command or from executing the gicadm export command, for example.

To import the contents of a file into a global index catalog, use the gicadm command with the import subcommand. For example:

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  import --file /usr/local/import-file --catalogName sampleCatalog

If the proxy server stops while a gicadm import task is being executed, the global index catalog workflow element is disabled. In this case, re-enable the global index catalog workflow element by using dsconfig, as follows, where sampleCatalog is the name of the global index catalog:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-workflow-element-prop --element-name sampleCatalog set enabled:true

23.7.1.9 Exporting Contents of a Global Index Catalog to a Directory

To export the contents of a global index catalog to a directory, use the gicadm command with the export subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  export --exportDirectory directory-path --catalogName sampleCatalog

23.7.1.10 Associating a Global Index Catalog With a Distribution Element

To associate a global index catalog with a distribution element, use the gicadm command with the associate subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  associate --catalogName sampleCatalog --distributionWorkflowElement element-name

When the global index catalog is associated with a distribution workflow element, the global index catalog will be listed in the properties of the distribution. To confirm which global index catalog is associated to a distribution, use the dsconfig get-workflow-element-prop command. For information on workflow elements, see Section 17.1.8, "Configuring Workflow Elements Using dsconfig."

23.7.1.11 Disassociating a Global Index Catalog From a Distribution Element

To disassociate a global index catalog from a distribution topology, you must know the distribution workflow element with which the global index catalog is associated. To confirm the name of the distribution workflow element that is using the global index catalog, view the properties of the distribution topology by using the dsconfig get-workflow-element-prop command.

To disassociate a global index catalog from a distribution workflow element, use the gicadm command with the disassociate subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
 disassociate --distributionWorkflowElement element-Name

23.7.1.12 Adding a Global Index to a Global Index Catalog

To add a new global index to an existing global index catalog, for example to map a new attribute, use the following procedure. This procedure creates and adds the global index to the global index catalog. It is not possible to create a global index without adding it to a global index catalog.

Before you begin, you must already have configured a global index catalog.

Use the gicadm command with the add-index subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  add-index --catalogName sampleCatalog --attributeName telephoneNumber

23.7.1.13 Removing a Global Index From a Global Index Catalog

Use the gicadm command with the remove-index subcommand.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  remove-index --catalogName sampleCatalog --attributeName telephoneNumber

23.7.2 Replicating Global Index Catalogs

To ensure high availability, global index catalogs should be replicated. You can use a standard hardware load balancer and configure global index catalogs replication in a deployment, as shown by the graphic in Section 3.2.7, "Configuration 7: Multiple Replicated Proxies."

This section contains the following topics:

• Section 23.7.2.1, "Creating a Replicated Topology and Enable Global Index Catalog Replication"

• Section 23.7.2.2, "Enabling Global Index Catalog Replication"

• Section 23.7.2.3, "Initializing Global Index Catalog Replication"

• Section 23.7.2.4, "Disabling Global Index Catalog Replication"

• Section 23.7.2.5, "Viewing the Status of a Replicated Global Index Catalog Configuration"

• Section 23.7.2.6, "Logging of Replication Activities"

• Section 23.7.2.7, "Lifecycle Examples for Replicated Global Index Catalogs"

23.7.2.1 Creating a Replicated Topology and Enable Global Index Catalog Replication

This section describes how to create a replicated topology with three proxy instances and enable global index catalog replication, as illustrated in Figure 23-1.

Figure 23-1 Replicated Global Index Catalogs

Description of ''Figure 23-1 Replicated Global Index Catalogs''

To create a replicated topology and enable global index catalog replication:

1. Install at least two proxy instances in your server topology.

   These instances should be on separate physical machines, for redundancy.

2. Configure a global index catalog for each instance of the proxy in your topology and add one or more global indexes.

   For more information on configuring a global index catalog using the gicadm command, see Section 23.7.1.1, "Creating a Global Index Catalog Containing Global Indexes."

3. Enable global index catalog replication.

   The proxy instance whose global index catalog is to be replicated across the topology is referred to, for the purposes of CLI syntax, as the local instance, while the other proxy instance declared in the command is referred to as the remote instance. For more information on running the gicadm enable-replication command, see Section 23.7.2.2, "Enabling Global Index Catalog Replication."

   Repeat this step for each proxy that is part of your replicated topology.

4. Choose a proxy instance on which to initialize replication. Consider which proxy instance has the most up to date global index catalog content.

   Otherwise, you can import the LDIF file to each proxy that is part of the topology. See Section 23.7.1.8, "Importing Content into a Global Index Catalog."

5. On the proxy instance chosen in the previous step, run the gicadm initialize-replication --all command. For more information, see Section 23.7.2.3, "Initializing Global Index Catalog Replication."

   Note:

   When using a global index catalog with replicated remote LDAP servers, only one remote LDAP server must handle write operations if such operations can concurrently modify the same value and if that value is indexed. For this, you could set the weights in your load balancing workflow element to direct all write traffic to the same server. For more information, see Section 21.1.4, "Modifying Load Balancing Properties."

23.7.2.2 Enabling Global Index Catalog Replication

This command configures replication but does not initialize replication. The command is executed on the local host, declared by the -h option, using the administration port of the local host. The remote host is declared by the --remoteHost option, and must be a fully qualified host name or IP address. The command creates a global index catalog replication administrator with a bind ID of adminUID.

If you created global index catalogs during installation, the global index administrator is already created, with the same password as the directory manager. For more information on installing a distribution deployment with global index, see "To Configure Simple Distribution" section in Installing Oracle Unified Directory.

To enable replication of global index catalogs, use the gicadm enable-replication command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  enable-replication --catalogName sampleCatalog --adminUID adminUID
  --localReplicationPort 8989 --remoteReplicationPort 8989 \
  --remoteAdminPort 4444 --remoteHost host

This command updates the proxy configuration to replicate the content of the global index catalog called sampleCatalog on the local host. If one of the proxy instances in the topology already replicates the global index catalog, this command updates the configuration of all other proxy instances in the topology. It is therefore sufficient to execute the gicadm enable-replication once for the first two proxy instances in the topology, and once for each new proxy instance that is added to extend the topology.

The proxy instance on which you execute the command must be the instance whose replication port is declared by the --localReplicationPort option. It is this local instance whose global index catalog is replicated across the topology later by the gicadm initialize-replication command. The --remoteReplicationPort option will replicate the content of the global index catalog called sampleCatalog from the local instance on to the remote instance. The --remoteAdminPort is the administration port of the remote proxy instance.

You can declare the password for the local proxy instance in a file, by using the --adminPasswordFile suboption.

You can optionally declare a DN for binding to the remote server by using the --remoteBindDN suboption and the password for the remote proxy instance in a file, by using the --remoteBindPasswordFile suboption. If you do not declare these, the global administrator that is declared by --adminUID will be used to bind.

You can also optionally require the communication through the replication port of the local server to be secure, using the --localSecureReplication suboption, and the communication through the replication port of the remote server to be secure, using the --remoteSecureReplication suboption.

23.7.2.3 Initializing Global Index Catalog Replication

This command initializes the content of the global index catalog called sampleCatalog from the proxy instance on the server declared by the -h option to all instances that are part of the topology. The port specified is the administration port, and not the replication port.

1. To initialize the replication of a global index catalog to all proxy instances that are part of the replication topology, use the gicadm initialize-replication --all as follows:

   $ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
     initialize-replication --catalogName sampleCatalog \
     --adminUID adminUID --all
   

2. Check that replication is complete by using the gicadm status-replication command.

   If replication is complete, the status for all proxy instances in the topology is given as running replicated.

   Replication must be complete before restarting any proxy instances in the topology, for example after applying a patch.

   For information about using the gicadm status-replication command, see Section 23.7.2.5, "Viewing the Status of a Replicated Global Index Catalog Configuration."

23.7.2.4 Disabling Global Index Catalog Replication

To disable replication of global index catalogs, use the gicadm disable-replication command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  disable-replication --catalogName sampleCatalog --adminUID adminUID

The gicadm disable-replication command must be executed for each proxy instance in the topology on which you want to disable replication.

23.7.2.5 Viewing the Status of a Replicated Global Index Catalog Configuration

To view basic configuration information about a replicated global index catalog, use the gicadm status-replication command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  status-replication --catalogName sampleCatalog --adminUID adminUID

If you do not declare a catalog name, status information for all replicated global index catalogs is displayed.

23.7.2.6 Logging of Replication Activities

Replication logs are stored in the replication repair logs. Changes are recorded in the change logs. For information on accessing these logs, see Section 35.5.4, "Accessing Logs."

When replicating global index catalogs, provision disk space for change logs. By default, these logs store changes for a 24 hour period. Approximately 100Mb is required for 300,000 write operations. With the default value of 24 hours, the log must be configured based on the expected size of the service during that period. A hint is to provision approximately 150Gb for 5 000 modifications per second over 24 hours. For information how to configure logs, see Section 35.3, "Configuring Logs."

23.7.2.7 Lifecycle Examples for Replicated Global Index Catalogs

This section describes several typical lifecycle examples in which events take place in a replication topology. The basic replication topology used in all of these examples is the one created in Section 23.7.2.1, "Creating a Replicated Topology and Enable Global Index Catalog Replication."

Example 23-1 Restarting a Global Index Catalog in a Replicated Topology

The example illustrated by Figure 23-2, shows three proxy instances running with a replicated global index catalog. If proxy instance 3 goes down or is stopped, for whatever reason, follow these steps to ensure that the three instances of the proxy are replicated.

1. Issue the start-ds command on proxy instance 3.

2. You can verify if replication is complete by executing the gicadm status-replication command, as described in Section 23.7.2.5, "Viewing the Status of a Replicated Global Index Catalog Configuration."

Figure 23-2 Restarting a Global Index Catalog

Description of ''Figure 23-2 Restarting a Global Index Catalog''

Example 23-2 Adding a Global Index to a Replicated Global Index Catalog Topology

The example illustrated by Figure 23-3, shows three proxy instances running with a replicated global index catalog. If you want to add an attribute, for example, mail, to the replicated global index catalog, follow these steps.

1. First, run the command gicadm add-index mail on each of the three proxy instances.

2. Export the directory data under the distribution route from one of the remote LDAP servers to an LDIF file named file1 by using export-ldif.

3. Run split-ldif to generate GIC content in the specified directory.

4. On proxy instance 1, execute the command gicadm import --importDirectory directory-name.

5. On proxy instance 1, execute the gicadm initialize-replication --all command. This command pushes the changes from proxy 1 to all the other proxies in the topology, and adds the new global index.

Figure 23-3 Adding a Global Index to a Replicated Global Index Catalog Topology

Description of ''Figure 23-3 Adding a Global Index to a Replicated Global Index Catalog Topology''

Example 23-3 Overwriting the Contents of Replicated Global Index Catalogs

The example illustrated by Figure 23-4, shows three proxy instances running with a replicated global index catalog. To overwrite the content of the global index catalogs on proxy instances 2 and 3 with the content of the global index catalog on instance 1, follow these steps.

1. On proxy instance 1, execute the gicadm initialize-replication --all command. This replaces the content of the global index catalog on proxy instance 2 and 3 with the content of the global index catalog on proxy instance 1.

Figure 23-4 Overwriting the Contents of Replicated Global Index Catalogs

Description of ''Figure 23-4 Overwriting the Contents of Replicated Global Index Catalogs''

Example 23-4 Adding a Proxy to a Replicated Topology

The example illustrated by Figure 23-5, shows three proxy instances running with a replicated global index catalog. To add a fourth proxy instance with a replicated global index catalog, follow these steps on the new proxy instance.

1. On the new proxy instance 4, execute the gicadm create-catalog command.

2. Run the commandsgicadm add-index cn, gicadm add-index sn, and gicadm add-index mail.

3. Execute the gicadm associate command.

4. Run the following command:

   gicadm enable-replication --localReplicationPort replication port of 
   instance 4 --remoteHost name or IP address of host running instance 1
   

   This command configures replication between instance 1 and instance 4.

5. Run the initialize replication --from proxy 1 command.

Figure 23-5 Adding a Proxy to a Replicated Topology

Description of ''Figure 23-5 Adding a Proxy to a Replicated Topology''

23.7.3 Configuring Controls Required by the Global Index Catalog with Oracle Unified Directory

If you are using the proxy server with an Oracle Unified Directory directory server as the LDAP data source, the connections between the proxy and directory servers must be bound using the directory server's administrator ID. Otherwise, some configuration is required on the directory server to allow the global index catalog to function correctly.

If the global ACIs for controls have not been modified, then use the ldapmodify command to apply the following changes to the directory server:

dn: cn=Access Control Handler,cn=config
changetype: modify
add: ds-cfg-global-aci
ds-cfg-global-aci: 
(targetcontrol="2.16.840.1.113730.3.4.2 || 2.16.840.1.113730.3.4.17 |
| 2.16.840.1.113730.3.4.19 || 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 |
| 2.16.840.1.113730.3.4.16 || 1.3.6.1.1.13.1 || 1.3.6.1.4.1.42.2.27.9.5.9")
(version 3.0; acl "Anonymous control access"; allow(read) userdn="ldap:///anyone";)
 ds-cfg-global-aci: (targetattr="createTimestamp||creatorsName||modifiersName|
|modifyTimestamp||entryDN||entryUUID||subschemaSubentry||aclRights||aclRightsInfo")
(version 3.0; acl "User-Visible Operational Attributes"; allow (read,search,compare)
 userdn="ldap:///anyone";)

If you are deleting the ACI from an Oracle Unified Directory 11g R1 directory instance, then you must delete the following ACI:

dn: cn=Access Control Handler,cn=config
changetype: modify
delete: ds-cfg-global-aci
ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 ||
 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control access";
 allow(read) userdn="ldap:///anyone";)
ds-cfg-global-aci: (targetattr="createTimestamp||creatorsName||modifiersName||
modifyTimestamp||entryDN||entryUUID||subschemaSubentry")
(version 3.0; acl "User-Visible Operational Attributes"; allow
 (read,search,compare) userdn="ldap:///anyone";)

If you are deleting the ACI from an Oracle Unified Directory 11g R2 directory instance, then you must delete the following ACI:

dn: cn=Access Control Handler,cn=config
changetype: modify
delete: ds-cfg-global-aci
ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 ||
 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
 2.16.840.1.113730.3.4.16 || 2.16.840.1.113894.1.8.31") 
(version 3.0; acl "Anonymous control access"; allow(read)
 userdn="ldap:///anyone";)

Note:

The preceding OIDs are correct for an unmodified configuration of Oracle Unified Directory. If you change the default OIDs, modify the command include the correct OIDs.

The following controls are required for global index catalogs:

• The Pre-Read Control, with OID = 1.3.6.1.1.13.1

• The CSN Control, with OID = 1.3.6.1.4.1.42.2.27.9.5.9

23.8 Configuring Virtual ACIs

Each workflow is associated to an access control group which defines the list of ACIs that apply to operations handled by this workflow.

By default, an access control group is created known as "Local Backends." This access control group contains all ACIs coming from user data. You cannot delete it. If virtual ACIs are disabled for a workflow, then you must specify Local Backends as the access control group for that workflow. For the workflow for which virtual ACIs are enabled, you can specify any access control group.

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

This section describes how to configure virtual ACIs for a workflow, and includes the following topics:

• Section 23.8.1, "Configuring Virtual ACIs Using dsconfig"

• Section 23.8.2, "Configuring Access Control Groups Using ODSM"

23.8.1 Configuring Virtual ACIs Using dsconfig

This section describes how to configure virtual ACIs using dsconfig, and includes the following topics:

• Section 23.8.1.1, "Enabling Virtual ACIs for a Workflow"

• Section 23.8.1.2, "Disabling Virtual ACIs for a Workflow"

• Section 23.8.1.3, "Configuring Replication for Virtual ACIs"

23.8.1.1 Enabling Virtual ACIs for a Workflow

To enable virtual ACIs for a specific workflow, run the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
set-workflow-prop --workflow-name workflow1 --set virtual-aci-mode:true \
--set access-control-group:group1

In this example, group1 references an access control group. This access control group can be either Local Backends, which is created by default or any other access control group that you have created. For more information about creating access control groups, see Section 17.1.11, "Configuring Access Control Groups With dsconfig."

23.8.1.2 Disabling Virtual ACIs for a Workflow

To disable virtual ACIs for a specific workflow, run the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
set-workflow-prop --workflow-name workflow1 --set virtual-aci-mode:false \
--set access-control-group:"Local Backends"

Note:

You must bear the following points in mind when you disable virtual ACIs for a workflow:

• If you disable virtual ACIs, you must specify "Local Backends" as the access control group for this workflow.

• Disabling virtual ACIs for a specific workflow does not delete virtual ACIs from the associated access control group.

23.8.1.3 Configuring Replication for Virtual ACIs

You can configure replication of virtual ACIs through the --advanced mode of the dsreplication command.

To configure replication of virtual ACIs, perform the following steps:

1. Enable replication of virtual ACI.

   $ dsreplication enable \
     --host1 host1 --port1 4444 --bindDN1 "cn=Directory Manager" \
     --bindPasswordFile1 pwd-file1 --replicationPort1 8989 \
     --host2 host2 --port2 4444 --bindDN2 "cn=Directory Manager" \
     --bindPasswordFile2 pwd-file2--replicationPort2 8989 \
     --adminUID admin --adminPasswordFile admin-pwd-file \
   --advanced --baseDN virtual-acis -X -n
   

2. Initialize replication.

   $ dsreplication initialize --advanced --baseDN virtual-acis \
     --adminUID admin --adminPasswordFile admin-pwd-file \
     --hostSource host1 --portSource 4444 \
     --hostDestination host2 --portDestination 4444 -X -n
   

23.8.2 Configuring Access Control Groups Using ODSM

ODSM allows you to create access control elements for Oracle Unified Directory Proxy Servers. To do so, perform the following:

1. Connect to the directory server from ODSM, as described in Section 16.2, "Connecting to the Server Using ODSM."

2. Select the Configuration tab.

3. Select the General Configuration element.

   The properties are displayed in the right hand pane.

4. Expand Access Control Groups.

5. Click Add to specify at least one local back end, that will be handled by this proxy instance.

   Click Delete, if you want to delete those access control groups that are not associated with any workflow. Deleting an access control group will delete all ACIs contained in that access control group.