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.

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.

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.

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.

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.

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.

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.

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

$ 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:oracle14 \
--set rdbms-username:dbuser \
--set rdbms-password:dbuser-password \
--set enabled:true

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.

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

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.

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

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.

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
   

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.

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

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

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

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

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

$ 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

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

$ 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

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

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

          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

You can create an LDAP server extension using dsconfig command.

$ 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

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

$ 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

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.

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

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).

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

$ 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

Use dsconfig command to view the proxy workflow element properties.

$ 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

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

$ 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

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

$ 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

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.

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