20 Configuring Access to Remote Data Sources

The data stored remotely can be accessed including identity data stored in an RDBMS. You can configure communication between a proxy instance and one or more remote LDAP servers.

The following topics describe configuring access to remote data sources:

• Configuring Access to Identity Data Stored in an RDBMS

• Configuring Communication With Remote LDAP Servers

20.1 Configuring Access to Identity Data Stored in an RDBMS

You can create a sample virtual configuration based on an Oracle Unified Directory proxy instance that exposes identity data stored in an Oracle Database as LDAP entries.

The examples in this section create this virtual view of the identity data by configuring an RDBMS workflow element and its supporting components. The RDBMS workflow element allows LDAP clients to access the identity data using the LDAP protocol.

This section includes the following topics:

• Understanding the RDBMS Workflow Element Use Case.

• Configuring the RDMBS Workflow Element.

• Creating the Components to Communicate with the RDBMS.

• About Granting Access to the Virtual Data.

For an overview of the RDBMS workflow element, see Enabling LDAP Clients to Access Identity Data Stored in an RDBMS.

Note:

The examples in this section use the dsconfig command to create and configure the RDBMS workflow element and other 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 dsconfig.

20.1.1 Understanding the RDBMS Workflow Element Use Case

The deployment of RDBMS workflow element use case includes LDAP clients, Oracle Unified Directory proxy servers, RDBMS workflow element and Oracle Database.

The deployment of RDBMS workflow element use case is described in the following topics:

• About LDAP Clients

• About Oracle Unified Directory Proxy Server

• About RDBMS Workflow Element and Supporting Components

• About Oracle Database

20.1.1.1 About LDAP Clients

This section introduces LDAP clients.

In this use case, LDAP clients want to access the identity data in an Oracle Database (the RDBMS) using the LDAP protocol. These clients do not want to execute SQL queries to access this data.

20.1.1.2 About Oracle Unified Directory Proxy Server

This use case requires an Oracle Unified Directory proxy server as the interface between the LDAP clients and the Oracle Database.

The proxy server connects to the Oracle Database as dbuser. The dbuser must have read privileges on the PERSON, PHONE, and USER_GROUP SQL tables in the Oracle Database, because LDAP searches are performed in the use case examples. If dbuser also wants to create or update the identity data using the LDAP protocol, then additional privileges are required.

Note:

Examples illustrated in the following sections assume that the schema contains the following tables only for demonstrational purpose: PERSON, PHONE, USER_GROUP. In a real deployment, actual tables from the schema are to be used.

20.1.1.3 About RDBMS Workflow Element and Supporting Components

The Oracle Unified Directory proxy uses the following components to communicate with the Oracle Database:

The proxy uses the following components to communicate with the Oracle Database:

• An RDBMS extension manages the connectivity with the remote Oracle Database through JDBC, by periodically checking the response from the remote peer and providing valid connections maintained by the connection pool.

• An RDBMS workflow element retrieves the connections from the RDBMS extension element, performs mapping between LDAP entries and SQL tables, and executes operations received from the LDAP clients.

• An RDBMS workflow for the RDBMS entries exposes the naming context handled by the RDBMS workflow element.

• An access control group for the RDBMS workflow uses virtual ACIs to control access the virtual identity data.

For more information, see Creating the Components to Communicate with the RDBMS.

20.1.1.4 About Oracle Database

The RDBMS in this use case is an Oracle 11g Database or later, which is installed, running, and populated with the deployment's identity data.

This database contains information about user accounts in these SQL tables:

• The PERSON table contains user data, including the employee ID, first name, last name, password, employee number, and hire date.

• The PHONE table, which is linked to the to the PERSON table, contains employee phone numbers.

For more information about these tables, see Understanding the Sample Schema for PERSON and Phone Tables.

This database also has the following characteristics:

• Database system identifier (SID): orcl

• Database URL: myhost.example.com:1521:orcl

• Database user who connects to the database from the proxy: dbuser

• Database user password: dbuser-password

In addition, if group memberships are needed, then those tables also have to be defined in the database. For more information, refer Understanding the Sample Schema for USER_GROUP Table.

20.1.2 Configuring the RDBMS Workflow Element

Before you begin configuring the RDBMS workflow element and its supporting components, you need to perform the required preliminary tasks.

The required preliminary tasks are:

• Setting Up an Oracle Unified Directory Proxy Server

20.1.2.1 Setting Up an Oracle Unified Directory Proxy Server

This use case requires an Oracle Unified Directory proxy server as the interface between the LDAP clients and the Oracle Database that contains the identity data.

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.
2. Run the oud-proxy-setup script to set up the proxy server instance:

   $ export INSTANCE_NAME=db-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:

   • db-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.

20.1.2.2 Installing a JDBC Driver JAR File for the RDBMS

The Oracle Unified Directory RDBMS implementation relies on the JDBC standard to communicate with the underlying RDBMS. If you are using Oracle Database, Oracle JDBC driver is already included and no action is needed. However, if you are using a non Oracle Database, you must install the JDBC driver JAR file that corresponds to the RDBMS you are using.

To install a JDBC driver JAR file:

1. Download the JDBC driver corresponding to the RDBMS database release you are using.
2. Copy the JAR file for the step 1 to the following directory:

   OUD_INSTANCE_NAME/OUD/lib
   

3. Restart the Oracle Unified Directory instance. For example, on UNIX and Linux systems:

   $ OUD_INSTANCE_NAME/OUD/bin/stop-ds
   $ OUD_INSTANCE_NAME/OUD/bin/start-ds
   

   On Windows systems, use stop-ds.bat and start-ds.bat in the OUD_INSTANCE_NAME\OUD\bat directory.

20.1.3 Creating the Components to Communicate with the RDBMS

You can create the components required for the Oracle Unified Directory proxy to communicate with the RDBMS.

Components required for communicating with the RDBMS is described below:

• Creating an RDBMS Extension

• Creating an RDBMS Extension to Use Secure Connection

• Creating an RDBMS Workflow Element

• Creating a Workflow for the RDBMS Entries

• Creating an Access Control Group for the RDBMS Workflow

• Associating the Workflow to a Network Group

• Configuring the LDAP-SQL Mappings

20.1.3.1 Creating an RDBMS Extension

An RDBMS extension corresponds to one RDBMS instance. This use case has only one Oracle Database instance.

To create an RDBMS extension named ORCL1, use the dsconfig create-extension command:

$ dsconfig create-extension \
--type rdbms \
--extension-name ORCL1 \
--set jdbc-driver-class:oracle.jdbc.driver.OracleDriver \
--set jdbc-url:"jdbc:oracle:thin:@myhost.example.com:1521:orcl" \
--set target-database:oracle11 \
--set rdbms-username:dbuser \
--set rdbms-password:dbuser-password \
--set enabled:true

In this example:

• type must be rdbms to specify an RDBMS extension.

• extension-name specifies the name of the new extension as ORCL1.

• jdbc-driver-class and jdbc-url correspond to the specific RDBMS instance.

  The URL depends on the host and port on which the RDBMS is running. The structure also depends on the specific RDBMS you are using. This example sets these properties for an 11g Oracle Database. For other databases, refer to the documentation for the JDBC driver you are using.

• target-database specifies the type of the RDBMS you are using. For an 11g (and 12g) Oracle Database, specify oracle11.

• rdbms-username and rdbms-password properties specify the credentials used to execute SQL queries.

  All SQL queries will be performed using these credentials, without consideration for the originating LDAP client identity. The virtual ACIs used to restrict access to the RDBMS SQL data based on the LDAP client identities will be configured later.

For a description of all RDBMS extension properties, see the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

20.1.3.2 Creating an RDBMS Extension to Use Secure Connection

You can configure an RDBMS extension to use a secure connection to access the database and prior to it, the database must be configured to accept secure connections. For the proxy to establish secure connections with remote RDMBS servers, you need to configure a truststore. An RDBMS proxy extension targeting a secured connection to a remote RDBMS data source must reference the appropriate truststore manager in its configuration.This reference enables the RDBMS proxy extension to access the imported remote RDBMS server certificate, to accept the secure connection.

The following topics describe creating an RDBMS extension to use secure connection:

• Configuring Security Between the Proxy and RDBMS Servers

• Creating an RDBMS Extension using dsconfig

• Configurable RDBMS Extension Properties Relevant to Security

• Configurable Advanced Properties for Setting Up JDBC Truststore and Keystore

20.1.3.2.1 Configuring Security Between the Proxy and RDBMS Servers

This task highlights the main steps required to configure security for connections to remote RDBMS servers. See RDBMS Vendor's documentation for detailed steps on configuring a keystore for remote RDBMS server connections and obtaining the RDBMS server certificate.

Perform the following steps to configure security between proxy and RDBMS server using dsconfig:

1. If the remote RDBMS server requires client authentication to be passed from the proxy, perform the following sub-steps. If the remote RDBMS server does not require client authentication to be passed from the proxy, then proceed to Step 2 to configure a truststore.
   1. Configure a keystore on the Oracle Unified Directory proxy server for remote RDBMS server connections.
      To do this, use the Java keytool command to generate a certificate on the proxy server. The keystore must be configured manually. See Configuring Key Manager Providers to configure a keystore manually.

      Self-sign the certificate or have the certificate signed by an external certificate authority. See Configuring Key Manager Providers for information about self-signing the certificate.

   2. Configure a key manager provider on the proxy for the keystore for remote RDBMS server connections. See Configuring Key Manager Providers for configuring a key manager provider for remote RDBMS server. This key manager provider can be different to the one which is used for handling secure connections to clients.
   3. See RDBMS Vendor's documentation for detailed steps to be followed to have an RDBMS server to trust the Oracle Unified Directory proxy certificate present in the above keystore during authentication.
2. For the proxy to establish secure connections with the remote RDBMS server, configure a truststore.
   An RDBMS proxy extension targeting a secured connection to a remote RDBMS data source must reference the appropriate truststore manager in its configuration. This reference enables the RDBMS proxy extension to access the imported remote RDBMS server certificate, to accept the secure connection.
3. Each truststore requires a proxy trust manager provider. For example:
   1. To list the proxy trust manager providers, use the dsconfig list-trust-manager-providers command. For example:

      $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
      list-trust-manager-providers

   2. To create a proxy trust manager provider, use the dsconfig create-trust-manager-provider command. For example:

      $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager"-j pwd-file-X -n \
      create-trust-manager-provider \
      --provider-name Backend\ Servers \
      --type file-based --set enabled:true \
      --set trust-store-file:/localhost/config/backend-servers-truststore \
      --set trust-store-type:JKS \
      --set trust-store-pin-file:/installPath/config/backend-servers-truststore.pin

4. Import the certificates of the remote RDBMS servers into the proxy truststore.

20.1.3.2.2 Creating an RDBMS Extension Using dsconfig

You can configure an RDBMS extension in Oracle Unified Directory using the dsconfig command to use a secure connection to access the database.

To create an RDBMS extension name ORCL1 use dsconfig create-extension command:

$ dsconfig create-extension \
--type rdbms \
--extension-name ORCL1 \
--set jdbc-driver-class:oracle.jdbc.driver.OracleDriver \
--set jdbc-url:
'jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=%HOST NAME)(PORT=1522))(CONNECT_DATA=(SERVICE_NAME=orcl12))(security=(ssl_server_cert_dn="CN=Root, C=US")))'
--set target-database:oracle \
--set rdbms-username:system \
--set rdbms-password:password \
--set enabled:true \
--set use-ssl:true \
--set ssl-trust-manager-provider:rdbms_truststore

See Table 20-1 for information about RDBMS Extension Properties.

If you already have an extension configured in a non-secured mode, you can switch to secured mode by running the following commands:

$ dsconfig set-extension-prop \
--extension-name ORCL1 \
--set use-ssl:true \
--set jdbc-url:'jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=%HOST NAME)(PORT=1522))(CONNECT_DATA=(SERVICE_NAME=orcl12))(security=(ssl_server_cert_dn="CN=Root, C=US")))'  
--set ssl-trust-manager-provider:rdbms_truststore

Table 20-1lists the properties that need to be set as appropriate for secure connection.

The following example uses set-extension-prop to set TLS version and cipher suites using jdbc-connection-properties for Oracle database:

$ dsconfig set-extension-prop \
--extension-name ORCL1 \
--set jdbc-connection-properties:orcle.net.ssl_version=1.2 or 1.1 \

$ dsconfig set-extension-prop \
--extension-name ORCL1 \
--set jdbc-connection-properties:oracle.net.ssl_cipher_suites=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

Note:

Setting SSL protocol versions and cipher suites are not the same across different database vendors. Therefore, it is recommended that you refer to the corresponding database documentation to check how these properties can be set for the database over JDBC. RDBMS extension allows generic name-value pair properties to be set as per the database requirements. See, Configurable Advanced Properties for Setting Up JDBC Truststore and Keystore Details for more information on properties of JDBC truststore and keystore.

20.1.3.2.3 Configurable RDBMS Extension Properties Relevant to Security

You must set RDBMS Extension properties relevant to security using dsconfig to have a secured connection.

Table 20-1 lists the properties required to be set as appropriate for secure connection:

Table 20-1 RDBMS Extension Properties for Secured Connection

Property	Description
type	Must be rdbms to specify an RDBMS extension.
extension-name .	Specifies the name of the new extension as ORCL1
jdbc-driver-class and JDBC URL	Corresponds to the specific RDBMS instance.JDBC URL must be in URL form to activate a secure connection in the JDBC driver.
target-database	Specifies the type of the RDBMS you are using. For an 11g (and 12g) Oracle Database, specify Oracle11.
rdbms-username and rdbms-password	Specifies the credentials used to execute SQL queries.
use-ssl	Specifies a flag indicating a secure connection. The possible values are true or false based on the connection.
ssl-trust-manager-provider	Specifies the Trust Manager provider.
ssl-key-manager-provider	Specifies the Key Manager provider
jdbc-connection-properties	Lists the underlying JDBC driver properties as "name=value"
jdbc-is-factory-properties	Specifies flag indicating if the properties need to be set using javax.net.setConnectionFactoryProperty method. The possible values are true or false.

For a description of all RDBMS extension properties, see the Configuration Reference for Oracle Unified Directory.

20.1.3.2.4 Configurable Advanced Properties for Setting Up JDBC Truststore and Keystore Details

You must set the advanced properties to specify vendor-specific property name for truststore and keystore details. You must note that there are no specific JDBC standards for jdbc-connection-properties. Therefore, different vendors use different properties. Usually the database makes use of “javax.net.ssl.” prefix. Consequently the default values of all these properties are set to “javax.net.ssl.*”. Particularly, you do not require any additional configuration for Oracle Database.

If external non-Oracle databases do not use “javax.net.ssl.*” and instead use different names, for instance, IBM DB2 uses "sslTrustStoreLocation", then you must refer to JDBC vendor documentation and update the properties described as follows:

Table 20-2 Advanced Properties for Setting jdbc truststore and keystore

Property	Description
jdbc-truststore-prop-name	Specifies the vendor specific property name for specifying trust store, javax.net.ssl.trustStore is the default
jdbc-truststore-pwd-prop-name	Specifies the vendor specific property name for specifying trust store password,javax.net.ssl.trustStorePassword is the default
jdbc-truststore-type-prop-name	Specifies the vendor specific property name for specifying trust store type, javax.net.ssl.trustStoreType is the default
jdbc-keystore-prop-name	Specifies the vendor specific property name for specifying key store, javax.net.ssl.keyStore is the default
jdbc-keystore-pwd-prop-name	Specifies the vendor specific property name for specifying key store password. javax.net.ssl.keyStorePassword is the default
jdbc-keystore-type-prop-name	Specifies the vendor specific property name for specifying key store type. javax.net.ssl.keyStoreType is the default

For a description of all RDBMS extension properties, see Configuration Reference for Oracle Unified Directory.

20.1.3.3 Creating an RDBMS Workflow Element

You must create an RDBMS workflow element for each RDBMS extension you are using. You must also have configured an RDBMS extension before you create an RDBMS workflow element.

To create an RDBMS workflow element associated with the RDBMS extension you created in previous section, use the dsconfig create-workflow-element command:

$ dsconfig create-workflow-element \
--type rdbms \
--element-name ORCL1 \
--set rdbms-extension:ORCL1 \
--set suffix:o=db \
--set enabled:true

In this example:

• type must be rdbms, to specify an RDBMS workflow element.

• element-name specifies the name of the new RDBMS workflow element as ORCL1.

• rdbms-extension specifies the name of the extension associated with this workflow element as ORCL1.

• suffix specifies the suffix DN as o=db, which is the DN of all entries stored and exposed by this workflow element.

For a description of all RDBMS workflow element properties, see the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

20.1.3.4 Creating a Workflow for the RDBMS Entries

You must create a workflow to expose the naming context handled by the RDBMS workflow element. This workflow is defined by a naming context (base DN) and a workflow element that defines how Oracle Unified Directory should handle an incoming request.

To create a workflow associated with the RDBMS workflow element you previously created, use the dsconfig create-workflow command:

$ dsconfig create-workflow \
--workflow-name db \
--set base-dn:o=db \
--set workflow-element:ORCL1 \
--type generic \
--set enabled:true

In this example:

• workflow-name specifies the name of this configuration object as db.

• base-dn specifies the suffix associated with this workflow as o=db. This suffix must be the same as the suffix exposed by the RDBMS workflow element named ORCL1.

• workflow-element specifies the RDBMS workflow element as ORCL1.

For a description of all workflow properties, see the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

20.1.3.5 Creating an Access Control Group for the RDBMS Workflow

An RDBMS workflow is associated with an access control group that defines a list of ACIs that apply to the operations handled by the workflow.

To control access to the virtual directory view of data from the Oracle Database, you must enable and create virtual ACIs. When Oracle Unified Directory receives a request on a virtual directory data view, it uses the virtual ACIs and any authentication information provided by the user to allow or deny access to the requested data.

To create an access control group for the RDBMS workflow:

1. Create an access control group named orcl1 using the dsconfig create-access-control-group command:

   $ dsconfig create-access-control-group \
   --group-name orcl1
   

   By default, the new access control group orcl1 is empty, so at this point in the configuration, the virtual entries are exposed only to Oracle Unified Directory administrators.

2. Associate the access control group created in the previous step to the RDBMS workflow element using the dsconfig set-workflow-prop command:

   $ dsconfig set-workflow-prop \
   --workflow-name db \
   --set virtual-aci-mode:true \
   --set access-control-group:orcl1
   

In this example:

• workflow-name specifies that the workflow named db is protected by the virtual ACIs stored in the access control group named orcl1.

• virtual-aci-mode is set to true, so that all operations handling the ACI attribute manage this attribute as a virtual ACI. The attribute is no longer stored with user data. It is stored in the specific directory information tree (DIT) location "cn=virtual acis" in the Oracle Unified Directory proxy instance.

20.1.3.6 Associating 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, but it can be attached to several network groups.

To assign the db workflow to the default network group (network-group), use the dsconfig set-network-group-prop command:

$ dsconfig set-network-group-prop \
--group-name network-group \
--set workflow:db

You can now query the Oracle Unified Directory proxy to get the contents of the Oracle Database. By default, a dummy entry that corresponds to the base of the naming context exposed by the RDBMS workflow element is returned, since you have not configured the LDAP-SQL mappings yet.

To check your configuration, use the ldapsearch command:

$ ldapsearch –p oud-port -D "cn=directory manager" -w admin-password -b o=db objectclass=*

dn : o=db
o : db
objectclass : organization
objectclass :top

20.1.3.7 Configuring the LDAP-SQL Mappings

You must now map the LDAP attributes to the appropriate columns in the SQL PERSON, PHONE, and USER_GROUP tables in the Oracle Database.

The following topics describe how to configure the LDAP-SQL mappings in this use case:

• Understanding the Sample Schema for PERSON and Phone Tables

• Creating RDBMS Tables

• Creating Object Class Mappings

• Creating Attribute Mappings

• Testing the Mappings

• Using Passwords Stored in the RDBMS

• Understanding the Sample Schema for USER_GROUP Table

20.1.3.7.1 Understanding the Sample Schema for PERSON and Phone Tables

In this use case, the Oracle Database exposes two SQL tables, a PERSON table containing user data, and a PHONE table containing user phone numbers.

The LDAP entries are mapped to the SQL rows and columns in these tables. One LDAP entry (sqlPerson object class) corresponds to each row of the PERSON table. The rows in the PHONE table appear in the multi-valued LDAP telephoneNumber attribute in the corresponding person entry.

The equivalent SQL commands to create these SQL tables are:

CREATE TABLE PERSON (ID INT PRIMARY KEY, FIRST_NAME VARCHAR(40), LAST_NAME
VARCHAR(40), PASSWORD VARCHAR(10), EMPLOYEE_ID VARCHAR(40), EMPLOYEE_NUMBER
INT, HIRE_DATE date)

CREATE TABLE PHONE (PERSON_ID INT, PHONE_NUMBER VARCHAR(17), FOREIGN
KEY(PERSON_ID) REFERENCES PERSON(ID) ON DELETE CASCADE, PRIMARY
KEY(PERSON_ID, PHONE_NUMBER))

In this use case, the primary keys for the PERSON table are automatically generated by the RDBMS and are not managed or exposed to the LDAP clients. This configuration is typical, because the LDAP entries are virtualized from the RDBMS and thus should be transparent to LDAP client applications.

In the Oracle Database, the primary key auto increment relies on the concept of database sequence and triggers. The following SQL commands create a sequence for the PERSON table and configure a trigger to automatically generate primary keys.

CREATE SEQUENCE PERSON_SEQUENCE START WITH 1 INCREMENT BY 1
CREATE OR REPLACE TRIGGER PERSON_TRIGGER BEFORE INSERT ON PERSON REFERENCING 
NEW AS NEW FOR EACH ROW BEGIN SELECT PERSON_SEQUENCE.nextval
INTO :NEW.ID FROM dual; END;

20.1.3.7.2 Creating RDBMS Tables

You must create an RDBMS table object for each SQL table in the RDBMS that contains rows to be exposed as LDAP attributes and then associate these tables with an RDBMS workflow element.

To create the RDBMS tables for this use case, use the dsconfig create-rdbms-table command:

1. Create an RDBMS table named PERSON that corresponds to the SQL PERSON table in the Oracle Database and associate this table with the RDBMS workflow element named ORCL1:

   $ dsconfig create-rdbms-table \
     --set db-table-name:PERSON \
     --table-name PERSON \
     --element-name ORCL1 \
     --set primary-key-field:ID \
     --set primary-key-storability:false \
     --set db-sequence-name:PERSON_SEQUENCE \
     --type generic
   

   In this example:

   • table-name specifies the name of the table configuration object.

   • db-table-name specifies the name of the corresponding SQL table.

   • element-name specifies the name of the RDBMS workflow element to which this table is associated with.

   • primary-keyfield specifies the SQL column (or columns) that correspond to the SQL primary keys.

   • primary-key-storability specifies whether the primary key of this table can contain user-provided values. If set to true, key values can be inserted into this column by end-users

     This use case uses auto-generated primary keys, so primary-key-storability is set to false. In most deployments, the key management should be transparent to LDAP clients, so that the key is automatically generated by the RDBMS when a row is inserted.

   • db-sequence-name specifies the database sequence to generate the primary key field value when database sequences are used with triggers. This is the case for an Oracle Database.

2. Create an RDBMS table named PHONE that corresponds to the SQL PHONE table in the Oracle Database and associate the table with the RDBMS workflow element named ORCL1:

   $ dsconfig create-rdbms-table \
     --table-name PHONE \
     --element-name ORCL1 \
     --set db-table-name:PHONE \
     --set primary-key-field:PERSON_ID \
     --set primary-key-field:PHONE_NUMBER \
     --set cascade-delete-on-relation:true \
     --set join-type:many-to-one \
     --set join-rule:PHONE.PERSON_ID=PERSON.ID \
     --type generic
   

For a description of all RDBMS table properties, see the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

20.1.3.7.3 Creating Object Class Mappings

An object class mapping configuration object specifies the name of the LDAP object class that corresponds to the LDAP objects built from the SQL table content. If the object class is not defined in the server schema, it is added automatically to the server schema during server startup.

To create an object class mapping for the sqlPerson object class in the RDBMS workflow element, use the dsconfig create-objectclass-mapping command:

$ dsconfig create-objectclass-mapping \
  --mapping-name sqlPerson \
  --element-name ORCL1 \
  --set objectclass-name:sqlPerson \
  --set rdn-attribute:uid \
  --type generic

In this example:

• objectclass-name specifies the name of the LDAP object class that will appear in the objectclass attribute.

• rdn-attribute specifies uid as the LDAP attribute used as a naming attribute.

  In this use case, the uid attribute corresponds to the EMPLOYEE_ID column in the PERSON table, as shown in the next section.

20.1.3.7.4 Creating Attribute Mappings

You must create an attribute mapping configuration object for each SQL row exposed as a LDAP attribute.

The attribute mappings required for this use case are shown in the following table:

LDAP Attribute	SQL Table and Column
uid	PERSON:EMPLOYEE_ID
lastName	PERSON:LAST_NAME
firstName	PERSON:FIRST_NAME
employeeNumber	PERSON:EMPLOYEE_NUMBER
hireDate	PERSON:HIRE_DATE
userPassword	PERSON:PASSWORD
telephoneNumber	PHONE:PHONE_NUMBER

To create attribute mappings for the sqlPerson object class, use the dsconfig create-attribute-mapping command for each attribute shown in the previous table:

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name employeeID \
  --mapping-name sqlPerson \
  --set attribute-name:uid \
  --set field-name:EMPLOYEE_ID \
  --set table-name:PERSON \
  --element-name ORCL1 \
  --type generic

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name firstName \
  --mapping-name sqlPerson \
  --set attribute-name:firstName
  --set field-name:FIRST_NAME \
  --set table-name:PERSON \
  --element-name ORCL1 \
  --type generic

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name lastName \
  --mapping-name sqlPerson \
  --set attribute-name:lastName \
  --set field-name:LAST_NAME \
  --set table-name:PERSON \
  --element-name ORCL1 \
  --type generic

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name employeeNumber \
  --mapping-name sqlPerson \
  --set attribute-name:employeeNumber \
  --set field-name:EMPLOYEE_NUMBER \
  --set table-name:PERSON \
  --element-name ORCL1 \
  --type generic

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name hireDate \
  --mapping-name sqlPerson \
  --set attribute-name:hireDate \
  --set field-name:HIRE_DATE \
  --set table-name:PERSON \
  --element-name ORCL1 \
  --type generic

$ dsconfig create-attribute-mapping \
  --attribute-mapping-name telephoneNumber \
  --mapping-name sqlPerson \
  --set attribute-name:telephoneNumber \
  --set field-name:PHONE_NUMBER \
  --set table-name:PHONE \
  --element-name ORCL1 \
  --type generic

In these examples:

• attribute-mapping-name specifies a name for the mapping performed by this command.

• attribute-name specifies the LDAP attribute being mapped to the indicated SQL table and column.

• mapping-name specifies the object class.

• field-name and table-name specify the SQL column and table names for mapping the LDAP attribute.

20.1.3.7.5 Testing the Mappings

At this stage of the configuration, each row of the PERSON table is exposed as an instance of sqlPerson in the o=db suffix. The corresponding telephoneNumber (if it exists) is retrieved from the PHONE table.

To test these mappings, perform an LDAP search, as shown in the following example.

Note:

You must perform the following test as Directory Manager, because at this point, there are no ACIs granting access to the RDBMS workflow element content.

$ ldapsearch –p oud-port -D "cn=directory manager" -w admin-password -b  o=db objectclass=*

dn : o=db
o : db
objectclass : organizationalUnit
objectclass :top
dn : uid=53422345,o=db
objectclass : sqlPerson
objectclass :top
uid : 53422345
firstName : Joseph
lastName : Smith
employeeNumber : 172453
hireDate : 199505011220000.000Z
telephoneNumber : [phone]

...

The previous example shows the first entry returned by the ldapsearch command. If the mappings are configured correctly, the search returns virtual LDAP entries built from the SQL tables, according to the defined mapping rules.

20.1.3.7.6 Using Passwords Stored in the RDBMS

In the Oracle Database, the PASSWORD column in the PERSON table contains the user password.

To configure the RDBMS workflow element to allow LDAP clients to authenticate against the password stored in the Oracle Database:

1. Create an attribute mapping for the userPassword attribute using the dsconfig create-attribute-mapping command:

   $ dsconfig create-attribute-mapping \
     --attribute-mapping-name userPassword \
     --mapping-name sqlPerson \
     --set attribute-name:userPassword \
     --set field-name:PASSWORD \
     --set table-name:PERSON \
     --element-name ORCL1 \
     --type generic
   

   In this example:

   • attribute-name specifies userPassword as the LDAP attribute to map.

   • field-name and table-name specify the SQL column and table names for the mapping.

   • element-name specifies the ORCL1 RDBMS workflow element.

2. Configure the RDBMS workflow element using the dsconfig set-workflow-element-prop command, so that the workflow element can use the userPassword attribute for authentication:

   $ dsconfig set-workflow-element-prop \
     --element-name ORCL1 \
     --set password-attribute:userpassword \
     --set password-storage-scheme:"Salted SHA-512"
   

In this example:

• password-attribute specifies the attribute that contains the user password.

• password-storage-scheme specifies how the user password is stored in the Oracle Database.

  In this example, the user password is stored in the Oracle Database hashed using the Salted SHA-512 algorithm. Unlike in LDAP entries, hashed password values in SQL tables are not prefixed by the digest algorithm tag (such as {SSHA-512}).

20.1.3.7.7 Understanding the Sample Schema for USER_GROUP Table

Note:

If group membership details are stored across multiple tables, then you need to define the appropriate joins in the configurations.

In this section, the example illustrated is only for demonstrational purpose. In a real deployment scenario, you need to perform all configurations (rdbms table creation, objectclass mappings, attribute mappings) based on the actual tables.

In this use case, consider the following table:

CREATE TABLE USER_GROUP(ID NUMBER NOT NULL, GROUP_NAME VARCHAR2(10), GROUP_MEMBER VARCHAR2(40));

where GROUP_NAME column holds the group's name, while GROUP_MEMBER column holds the name of the member of the Group as follows:

Table 20-3 Group Name Table

ID	GROUP_NAME	GROUP_MEMBER
1234	Group 1	user1
1235	Group 1	user2
1236	Group 1	user3

Create RDBMS Table, Object class mappings and Attribute Mappings by referring the respective sections: Creating RDBMS Tables, Creating Object Class Mappings, and Creating Attribute Mappings .

For example,

$ dsconfig create-rdbms-table \
--set db-table-name:USER_GROUP \
--table-name USER_GROUP \
--element-name ORCL1 \
--set primary-key-field:ID \
--set primary-key-storability:false \
--set db-sequence-name:USER_GROUP_SEQUENCE \
--type generic


$ dsconfig create-objectclass-mapping \
--mapping-name sqlGroup \
--element-name ORCL1 \
--set objectclass-name:groupOfUniqueNames \
--set rdn-attribute:cn \
--type generic


$ dsconfig create-attribute-mapping \
--attribute-mapping-name groupCN \
--mapping-name sqlGroup \
--set attribute-name:cn \
--set field-name:GROUP_NAME \
--set table-name:USER_GROUP \
--element-name ORCL1 \
--type generic


$ dsconfig create-attribute-mapping \
--attribute-mapping-name groupUniquemember \
--mapping-name sqlGroup \
--set attribute-name:uniquemember \
--set field-name:GROUP_MEMBER \
--set table-name:USER_GROUP \
--element-name ORCL1 \
--type generic

Note:

To return the User's DN as uniquemember attribute values in the ldap search results for Groups, a Transformation should be specified.

A sample Transformation configuration is provided here. For more information, refer Understanding the Transformation Framework.

• Create transformation for attribute uniquemember:

  dsconfig create-transformation \ 
  --type map-attribute \
  --transformation-name uniquemember_transform \          
  --set client-attribute:uniquemember="{uid=%uniquemember%,o=db}" \
  --portProtocol LDAP

• Create workflow element for transformation:

  dsconfig create-workflow-element \
  --set next-workflow-element:ORCL1 \
  --set transformation:uniquemember_transform  \
  --portProtocol LDAP \
  --type transformations \
  --element-name uniquemem_transform_wfe \
  --set enabled:true
  
  dsconfig set-workflow-element-prop \
  --element-name uniquemem_transform_wfe \
  --add transformation:uniquemember_transform

• Create workflow for transformation:

  dsconfig create-workflow \
  --set base-dn:o=db \ 
  --set enabled:true \
  --set workflow-element:uniquemem_transform_wfe  \
  --workflow-name workflow1 \
  --type generic

• Set Network Group for transformation:

  dsconfig set-network-group-prop \
  --group-name network-group \
  --set workflow:workflow1

With the above configurations in place, LDAP search result is as follows:

dn: cn=group1,o=db
uniquemember: cn=user1,o=db
uniquemember: cn=user2,o=db
uniquemember: cn=user3,o=db
cn: group1
objectClass: top
objectClass: groupOfUniqueNames

20.1.4 About Granting Access to the Virtual Data

You can grant access to the virtual data by creating virtual ACI’s through ldap commands.

Note:

Your access control strategy for the RDBMS you are using depends on your corporate policies, so you must create virtual ACIs to follow those policies.

By default, the access control group named orcl1 created in Creating an Access Control Group for the RDBMS Workflow is empty. The virtual entries for the database are exposed only to Oracle Unified Directory administrators. Thus, the following search does not return any entries:

$ ldapsearch –p oud-port -D uid=53422345,o=db -w password -b o=db objectclass=*

The following command creates a virtual ACI granting full access to the owner of the virtual entry created from the Oracle Database:

ldapmodify –p oud-port -D "cn=Directory Manager" –w admin-password
dn : o=db
changetype : modify
add : aci
aci : (targetattr= "*") (version 3.0 ; acl "self example" ; allow (all) userdn="ldap:///self" ;)

If you retry the previous search using this new virtual ACI, each user is granted access to their own entry based on the uid:

ldapsearch –p oud-port -D uid=53422345,o=db -w password -b o=db objectclass=*

dn : uid=53422345,o=db
objectclass : sqlPerson
objectclass :top
uid : 53422345
firstName : Audrey
lastName : Smith
employeeNumber : 172453
hireDate : 199505011220000.000Z
telephoneNumber : [phone]

20.2 Configuring Communication With Remote LDAP Servers

Configuring communication between a proxy instance and one or more remote LDAP servers and the tasks associated with this is described in the following sections.

The following topics describe the communication with remote LDAP:

• Configuring LDAP Server Extensions

• Configuring Proxy LDAP Workflow Elements

• Configuring the Bind Mode

Note:

For more information about communicating with remote LDAP servers, see Understanding How to Enable Communication with a Remote LDAP Server.

20.2.1 Configuring LDAP Server Extensions

LDAP server extensions can be configured to communicate with the remote LDAP servers.

The following topics describe the tasks involved in configuring LDAP server extensions:

• Viewing the Existing LDAP Server Extensions

• Viewing LDAP Server Extension Properties

• Viewing Advanced LDAP Server Extension Properties

• Creating an LDAP Server Extension

• Modifying the Properties of an LDAP Server Extension

• Modifying the Advanced Properties of an LDAP Server Extension

• Modifying the LDAP Data Source Monitoring Connection Properties

20.2.1.1 Viewing the Existing LDAP Server Extensions

This section describes the procedure to view the existing LDAP server extensions.

To view a list of all the LDAP server extensions configured for a proxy instance, use the dsconfig list-extensions command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  list-extensions 

Extension  : Type
-----------:---------------------
gi-catalog : global-index-catalog
proxy1     : ldap-server
proxy2     : ldap-server

The extensions with type ldap-server are the LDAP server extensions. You should have one LDAP server extension for each remote LDAP server.

20.2.1.2 Viewing LDAP Server Extension Properties

You can view the LDAP server extension properties using the dsconfig command.

To view the properties of a specific LDAP server extension, use the dsconfig get-extension-prop command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  get-extension-prop --extension-name proxy1

Property                   : Value(s)
---------------------------:---------
enabled                    : true
remote-ldap-server-address : server1.example.com
remote-ldap-server-port    : 1389
page-size                  : 0

The following properties are displayed:

• enabled

  Indicates if the LDAP server extension is enabled (true) or not (false)

• remote-ldap-server-address and remote-ldap-server-port

  Indicates the address and port of the remote LDAP server to which requests will be forwarded

• monitoring-bind-dn and monitoring-bind-password

  These properties are displayed only if you specify the --advanced option. They provide the credentials of the user that the extension will use to perform monitoring of the data source. If these properties have not been changed from the default, then they are not displayed. Monitoring is then performed anonymously.

  To configure these properties, see Monitoring the Server with LDAP.

• page-size

  Indicates the default page size to be considered when requesting entries from the Directory Server backend associated with this LDAP Server Extension.

  This restricts the number of entries (when configured > 0) that can be requested from the backend server to be configured with this extension. It is especially useful when clients while accessing OUD Proxy use a search query that does not explicitly contain the paged search option, as the search may timeout if the query results are quite large.

  This option should have a value less than or equal to the size limit parameter specified by the backend to avoid erroneous results.

  This parameter is honored only when the client does not provide the page size search option in its request.

  The default value is 0.

20.2.1.3 Viewing Advanced LDAP Server Extension Properties

You can view all of the LDAP server extension properties using dsconfig command.

To view all of the LDAP server extension properties, use the dsconfig --advanced get-extension-prop command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  --advanced get-extension-prop --extension-name proxy1

Properties similar to the following are displayed.

          Property                            Value(s)
         ----------------------------------------------------------------------
    1)   enabled                             true
    2)   java-class                          com.sun.dps.server.workflowelement
                                             .proxyldap.LDAPServerExtension
    3)   monitoring-check-interval           30000
    4)   monitoring-connect-timeout          5000
    5)   monitoring-inactivity-timeout       120000
    6)   monitoring-ping-timeout             5000
    7)   page-size                           0
    8)   pool-increment                      5
    9)   pool-initial-size                   10
    10)  pool-max-size                       1000
    11)  pool-max-write                      0
    12)  pool-release-connection-interval    300000
    13)  pool-use-max-write                  false
    14)  proxied-auth-use-v1                 false
    15)  remote-ldap-server-address          localhost
    16)  remote-ldap-server-connect-timeout  10000
    17)  remote-ldap-server-port             1389
    18)  remote-ldap-server-read-only        false
    19)  remote-ldap-server-read-timeout     10000
    20)  remote-ldap-server-ssl-policy       never
    21)  remote-ldap-server-ssl-port         636
    22)  saturation-precision                5
    23)  ssl-client-alias                    -
    24)  ssl-key-manager-provider            -
    25)  ssl-trust-all                       false
    26)  ssl-trust-manager-provider          -
    27)  ssl-protocol		          system default value
    28)  ssl-cipher-suite                    system default value

Note:

Most of the advanced properties (except SSL properties) are set by default when the LDAP server extensions are created.

To modify these values, see Modifying the Properties of an LDAP Server Extension.

To understand about the monitoring properties, see Modifying the LDAP Data Source Monitoring Connection Properties.

To understand about the SSL (security) properties, see Configuring Security Between the Proxy and the Data Source.

To understand about system default values, see Supported TLS Protocols and Cipher Suites by Oracle Unified Directory

20.2.1.4 Creating an LDAP Server Extension

You can create an LDAP server extension using dsconfig command.

To create a new LDAP server extension, use the dsconfig create-extension command, as follows:

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

The extension type must be ldap-server. The name of the new extension is defined by extension-name, in this example DS-proxy5.

You must also specify the name of the remote LDAP server with which this extension is associated (remote-ldap-server-address). You can specify either the hostname or the IP address of the remote LDAP server.

If you do not specify a remote-ldap-server-port, the default LDAP port of 1389 is assumed.

20.2.1.5 Modifying the Properties of an LDAP Server Extension

This section describes the procedure to modify the properties of an LDAP server extension.

To modify the LDAP server extension properties, use the set-extension-prop subcommand. This subcommand enables you to do the following:

• Set whether the LDAP server extension is enabled (true) or not (false)

• Modify the remote LDAP directory server address and port (remote-ldap-server-address and remote-ldap-server-port)

• Set the credentials of the user that the extension will use to perform monitoring of the data source (monitoring-bind-dn and monitoring-bind-password). If left blank, the monitoring will be performed anonymously, which is the default.

For example, changing the remote LDAP server is a common operation. You must set the new remote LDAP server address and port, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-extension-prop \
  --extension-name DS-proxy5 \
  --set remote-ldap-server-address:DS5-hostname \
  --set remote-ldap-server-port:3388

To modify advanced LDAP server extension properties, see Modifying the Advanced Properties of an LDAP Server Extension.

20.2.1.6 Modifying the Advanced Properties of an LDAP Server Extension

This section lists the advanced properties that you can configure.

You can configure the following advanced properties:

• pool-increment

  The increment by which the size of a connection pool is increased or decreased. If the remote-ldap-server-ssl-policy property is set to user, two pools of connections are created and the incremental change in size of each pool is set to pool-increment.

  The default value is 5 connections.

• pool-initial-size

  The initial size of a connection pool. This is the initial number of connections to be created when a pool is initialized. The pool-initial-size property is also the minimum size of a pool.

  The default value is 10 connections.

  If the remote-ldap-server-ssl-policy property is set to user, two pools of connections are created and the initial size, and minimum size, of each pool is set to pool-initial-size. Therefore there can initially be twice the total number of connections indicated in pool-initial-size.

  For more information, see Understanding the Modes of Secure Connection.

• pool-max-size

  The maximum size of a connection pool. This is the maximum number of connections that a pool can allocate. If the remote-ldap-server-ssl-policy property is set to user, two pools of connections are created and the maximum size of each pool is set to pool-max-size.

  The default value is 1000 connections.

• pool-max-write

  The maximum number of write connections that a connection pool can allocate at the same time. This is an integer. This parameter is taken into account only if the pool-use-max-write parameter is set to true.

  The default value is 0 connections.

• pool-release-connection-interval

  The time after which a connection is considered by the proxy to be unused if no traffic has been sent on it. This reduces the size of the pool of connections, if the pool has been previously increased. If the number of unused connections is greater than pool-increment, then the size of the pool is reduced by pool-increment. This means that unused connections are closed and are removed from the pool.

  The default value is 300000 milliseconds (30 seconds).

• pool-use-max-write

  If this boolean is set to true, the pool-max-write parameter is taken into account, otherwise it is not.

  By default, pool-use-max-write is set to false.

• proxied_auth_use_v1

  When using the proxy authorization control mode, the default version of the control is v2. To use an older version for compatibility reasons, set proxied-auth-use-v1 to true.

  By default, proxied-auth-use-v1 is set to false.

  For more information about controls, see LDAP Controls and Operations Reference.

• remote-ldap-server -read-timeout

  The timeout for reads. If the timeout is reached before the remote LDAP server sends back a response, an error is returned by the proxy to the client.

  By default, this value is 10000 milliseconds (10 seconds).

• saturation-precision

  The saturation precision is used in calculating the saturation threshold. Since the saturation limit can vary as requests are sent and received, the saturation precision indicates how much change the saturation should get before the saturation is taken into account.

  By default the saturation can vary by 5% before it is taken into account.

• ssl-protocol

  Governs the SSL/TLS protocol that would be used during SSL communication with the remote LDAP server. This property takes system default values and can be overridden with valid SSL/TLS protocols as required. See Supported TLS Protocols and Cipher Suites by Oracle Unified Directory to understand about system default values.

• ssl-cipher-suite

  Governs the SSL/TLS cipher suite that would be used during SSL communication with the remote LDAP server. This property takes system default values and can be overridden with valid SSL/TLS cipher suites as required. See Supported TLS Protocols and Cipher Suites by Oracle Unified Directory to understand about system default values.

• allow-server-supported-controls

  If the allow-server-supported-controls property is set to true, the LDAP Server Extension will fetch all the controls set in supportedControl of the remote backend’s RootDSE during initialization. It will pass only those controls to the remote server and will ignore and not send any other LDAP controls to the remote backend in an LDAP request. However, if this property is set to false, then the LDAP Server Extension will honor values set in the ignored-ldap-controls property.

• ignored-ldap-controls

  A list of OIDs of LDAP controls which will be ignored and not sent to the remote backend.

• remote-ldap-server-guid

  Specifies the name of the attribute that stores LDAP entry's global unique identifier (GUID) value in the remote LDAP server. For example, in case of Active Directory, it is objectGUID.

• server-guid-name

  Specifies the attribute name, which will contain the transformed value of remote-ldap-server-guid in the entries returned by the LDAP Server extension. The default value is orclguid.

• remote-ldap-server-additional-guids

  Specifies the names of the attributes other than what is configured in remote-ldap-server-guid property, which may be storing GUID values in the remote LDAP server. When configured, the attribute value is transformed into orclguid format by the LDAP Server extension.

The monitoring properties are described in Modifying the LDAP Data Source Monitoring Connection Properties.

The SSL properties are security features. For information about these properties, see Configuring Security Between the Proxy and the Data Source.

To modify the advanced LDAP server extension properties, use the set-extension-prop --advanced command.

Note:

These advanced properties are set by default and typically are not modified.

An example of an advanced property that you may want to change is the pool-max-size. If you have a powerful remote LDAP server and you have configured the proxy so that it receives a maximum of requests, you can increase the pool-max-size as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-extension-prop --advanced \
  --extension-name DS-proxy5 \
  --set pool-max-size:2000

20.2.1.7 Modifying the LDAP Data Source Monitoring Connection Properties

Using the dsconfig --advanced command for the LDAP server extension, you can view or change the following monitoring properties. All properties relate to proactive monitoring unless otherwise specified.

• monitoring-check-interval

  The monitoring check interval is the interval in milliseconds at which the proxy proactive monitoring checks the data source.

  The default value is 30000 milliseconds (30 seconds).

  For more information, see Configuring a Proxy Instance to Monitor Back-End Servers.

• monitoring-connect-timeout

  The maximum time in milliseconds after which the proactive monitoring facility will stop attempting to connect to the remote LDAP server.

  The default value is 5000 milliseconds (5 seconds). 0 means unlimited.

• monitoring-inactivity-timeout

  The time interval in milliseconds after which an idle connection is regularly checked to avoid connection closure by the remote server. The value of this parameter must be superior to the monitoring-check-interval.

  The default value is 120000 milliseconds (120 seconds).

• monitoring-ping-timeout

  The maximum time in milliseconds the proactive monitoring attempts to ping the remote server.

  The default value is 5000 milliseconds (5 seconds).

• remote-ldap-server-read-timeout

  The maximum time in milliseconds during which the LDAP Server Extension waits for a response from the remote server before the connection is regarded as having failed. 0 means unlimited.

• remote-ldap-server-connect-timeout

  The maximum time in milliseconds during which monitoring attempts to connect to the remote server before the connection is regarded as having failed. 0 means unlimited.

  The default is 10000 milliseconds (10 seconds).

20.2.2 Configuring Proxy LDAP Workflow Elements

You can configure the LDAP proxy workflow elements required to communicate with the remote LDAP server by creating a proxy LDAP workflow element.

The following topics describe the LDAP proxy workflow elements configuration:

• Viewing the Existing Proxy LDAP Workflow Elements

• Viewing the Properties of a Proxy LDAP Workflow Element

• Creating a Proxy LDAP Workflow Element

• Modifying the Properties of an LDAP Server Extension

20.2.2.1 Viewing the Existing Proxy LDAP Workflow Elements

Use dsconfig command to view a list of all the workflow elements configured on a particular proxy server instance.

To view a list of all the workflow elements configured on a particular proxy server instance, use the dsconfig list-workflow-elements command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  list-workflow-elements

Workflow Element : Type               : enabled
-----------------:--------------------:--------
adminRoot        : ldif-local-backend : true
load-bal-we1     : load-balancing     : true
proxy-we1        : proxy-ldap         : true
proxy-we2        : proxy-ldap         : true

The proxy workflow elements are the ones with the type proxy-ldap.

20.2.2.2 Viewing the Properties of a Proxy LDAP Workflow Element

Use dsconfig command to view the proxy workflow element properties.

To view the proxy workflow element properties, use the dsconfig get-workflow-element-prop command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  get-workflow-element-prop --element-name proxy-we1

Property                              : Value(s)
--------------------------------------:--------------------
client-cred-mode                      : use-client-identity
enabled                               : true
ldap-server-extension                 : proxy1
remote-ldap-server-bind-dn            : -
remote-ldap-server-bind-password      : -
use-proxy-auth                        : false

The following properties are displayed:

• client-cred-mode

  This indicates how the proxy connects to the remote LDAP server. In this example, the status is use-client-identity, which means that the proxy will connect to the remote LDAP server with the same credentials that the client used to connect to the proxy.

  This is the default mode.

  For more information, see Configuring Security Between the Proxy and the Data Source.

• enabled

  This indicates if the workflow is enabled (true) or not (false)

• ldap-server-extension

  This indicates the name of the LDAP server extension with which the workflow element is associated

• remote-ldap-server-bind-dn and remote-ldap-server-bind-password

  This indicates the credentials of the user that the proxy uses to connect to the remote LDAP server when client-cred-mode is use-specific-identity or use-proxy-auth.

20.2.2.3 Creating a Proxy LDAP Workflow Element

You must have configured an LDAP server extension before you create a proxy LDAP workflow element.

To create a proxy LDAP workflow element, use the dsconfig create-workflow-element command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-workflow-element \
  --element-name proxy-we5 \
  --type proxy-ldap \
  --set enabled:true \
  --set client-cred-mode:use-client-identity \
  --set ldap-server-extension:DS-proxy5

The workflow element type must be proxy-ldap. The name of the new proxy LDAP workflow element is defined by element-name, in this example proxy-we5.

The client credential mode (client-cred-mode) indicates how the proxy will connect to the remote LDAP server. In this example, the credential mode is use-client-identity, which means that the proxy will connect to the remote LDAP server with the same credentials as those used by the client to connect to the proxy. This is the default mode.

Note:

• If you use Oracle Unified Directory remote LDAP servers and the client credential mode is set to use-proxy-auth, the user as which you are connecting must exist on the remote LDAP server. If the user does not exist, requests will be rejected. If you cannot guarantee that the user exists on the remote LDAP server, rather set the client credential mode to use-specific-identity.

• If the user deployment performs an internal operations then you must define the root credentials. For example, if you are using RDN changing as described in Performing RDN Changing Configuration, then the root credentials are defined by the following properties:

  remote-root-dn

  remote-root-password

  These are the credentials for the root user of the remote LDAP server when the server performs internal operations.

• When managing passwords in a proxy LDAP workflow element (remote-ldap-server-bind-password or remote-root-passord), the following syntax are valid:

  <password-value> or file://<password-file>

For more information, see Configuring Security Between the Proxy and the Data Source.

20.2.2.4 Modifying the Properties of a Proxy LDAP Workflow Element

To modify the proxy LDAP workflow element properties, use the set-workflow-element-prop command.

You can modify the following properties:

• Set whether the proxy LDAP workflow element is enabled (true) or not (false)

• Set the client credential mode that is used (client-cred-mode)

• Associate an LDAP server extension, to indicate which remote LDAP server to use (ldap-server-extension)

• Set the credentials of the user that the proxy uses to connect to the remote LDAP server (remote-ldap-server-bind-dn and remote-ldap-server-bind-password). The following syntaxes are supported:

  • <password-value>

  • file://<password-file>

  Passing a password in clear on the command line is supported but not recommended. It is recommended to use a password-file. You can delete the password-file once the command is executed.

For example, if you want to modify the LDAP server extension used by the workflow element in order to use a different remote LDAP server, do the following:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-workflow-element-prop --advanced \
  --element-name proxy-we5 \
  --set remote-ldap-server-bind-dn:uid=Specific\ User,dc=example,dc=com \
  --remote-ldap-server-bind-password:file://pwd-file \
  --set ldap-server-extension:DS-proxy3 \
  --set client-cred-mode:use-specific-identity

20.2.3 Configuring the Bind Mode

You can configure the Bind Mode and its parameters to optimize the server.

The following topics explain how to configure the Bind Mode and its parameters:

• About Configuring the Bind Mode

• Configuring the Bind Mode Parameters to Optimize the Server

20.2.3.1 About Configuring the Bind Mode

Learn how the proxy LDAP workflow element processes an authenticated operation that is executed by the end user.

When an end user executes an authenticated operation, the proxy LDAP workflow element receives the following two distinct operations:

1. A BIND operation that authenticates the user against the remote server.

2. An operation to execute.

When a bind operation is executed, the proxy LDAP workflow element retrieves a connection from the LDAP server extension, performs the BIND operation, then releases the connection.

When the actual operation arrives, the proxy LDAP workflow element again retrieves a connection from the LDAP server extension. If a connection is found that is still bound with the appropriate credentials, that connection is reused. If not, a new connection must be authenticated. This additional authentication operation is called a silent bind.

The set of credentials used to perform a silent bind is determined by the bind mode, which is a property of the LDAP workflow element. These credentials can be the client credentials or the proxy credentials. Table 20-4 lists the bind modes that are supported by Oracle Unified Directory.

Table 20-4 Supported Bind Modes by Oracle Unified Directory

Mode	Description
use-client-identity	Use the client credentials to perform the silent bind.
use-specific-identity	Use the proxy credentials to perform the silent bind.

20.2.3.2 Configuring the Bind Mode Parameters to Optimize the Server

You can configure additional parameters to tweak the behavior of the server.

For each of the bind modes described in Table 20-4, you can configure additional parameters to tweak the behavior of the server.

For a description of these parameters, see the following sections:

• About Configuring the use-client-identity Bind Mode

• About Configuring the use-specific-identity Bind Mode

20.2.3.2.1 About Configuring the use-client-identity Bind Mode

If you set the bind mode to use-client-identity, then the server uses the client credentials to perform a silent bind — unless specific parameters prevent it from doing so.

For information about the parameters that prevent the server from using the client credentials, see the following sections:

Using Include and Exclude Lists

You can configure the following lists:

• Include List: Lists the suffixes that are handled by the remote server.

• Exclude List: Lists the suffixes that are not handled by the remote server.

If the client bind DN is a descendant of one DN on the include list, and the client bind DN is not a descendant of any DN on the exclude list, the proxy server uses the client credentials to perform a silent bind. Otherwise the proxy server uses the proxy credentials to perform the silent bind. If both lists are empty, the proxy server always uses the client credentials.

The include and exclude lists are not mutually exclusive and can be used simultaneously. However, it is recommended that you define only one list. In addition, you cannot define the same suffixes in both the lists.

Using the never-bind Parameter

The never-bind parameter is applicable whenever the proxy needs to perform a bind with the client credentials. If this flag is set to true, the proxy server reads the user entry from the remote data source, and validates the user password itself, instead of forwarding the bind to the remote server.

Note:

The credentials used to read the user entry are proxy credentials, which are defined in the remote-ldap-server-bind-dn and remote-ldap-server-bind-password properties of the proxy LDAP workflow element.

If the incoming bind operation contains controls that are critical, an error result is returned as controls dedicated to bind operations are incompatible with the never-bind feature.

Note:

If the proxy uses its own credentials to read the user entry, then you can add the proxy authorization control to operations to indicate the identity of the client at the origin of the request. The value of the use-proxy-auth property determines whether the control should be added.

20.2.3.2.2 About Configuring the use-specific-identity Bind Mode

When the bind mode is set to use-specific-identity, the proxy server uses the proxy credentials to perform all silent binds.

The proxy credentials are defined in the following properties of the proxy LDAP workflow element: remote-ldap-server-bind-dn and remote-ldap-server-bind-password.

In use-specific-identity bind mode, you can set the following parameters:

Using the use-proxy-auth Parameter

If the use-proxy-auth flag is set to true, the proxy server adds a proxy authorization control to all requests, except bind requests. The value of the proxy authorization identifier is the client bind DN.

Using the never-bind Parameter

The never-bind parameter is applicable whenever the proxy needs to perform a bind with the client credentials. When this flag is set to true, the proxy server reads the user entry from the remote data source, and validates the user password itself, instead of forwarding the bind to the remote server.

Note:

The credentials used to read the user entry are proxy credentials, which are defined in the remote-ldap-server-bind-dn and remote-ldap-server-bind-password properties of the proxy LDAP workflow element.