This chapter describes how to configure access to data stored remotely, including how to access identity data stored in an RDBMS and how to configure communication between a proxy instance and one or more remote LDAP servers.
This chapter contains the following sections:
Section 20.1, "Configuring Access to Identity Data Stored in an RDBMS"
Section 20.2, "Configuring Communication With Remote LDAP Servers"
This section describes a use case that creates 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:
Section 20.1.1, "Understanding the RDBMS Workflow Element Use Case"
Section 20.1.2, "Before You Begin Configuring the RDBMS Workflow Element"
For an overview of the RDBMS workflow element, see Section 12.1.1, "Enabling LDAP Clients to Access Identity Data Stored in an RDBMS."
Note:
The examples in this section use thedsconfig
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 Section A.2.4, "dsconfig."
The deployment for this use case includes the following components:
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
and PHONE
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:
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 Section 20.1.3, "Creating the Components to Communicate with the RDBMS."
The RDBMS in this use case is an 11g Oracle Database, 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 Section 20.1.3.6.1, "Understanding the 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
Before you begin configuring the RDBMS workflow element and its supporting components, perform these required preliminary tasks:
Section 20.1.2.1, "Setting Up an Oracle Unified Directory Proxy Server"
Section 20.1.2.2, "Installing a JDBC Driver JAR File for the RDBMS"
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:
Ensure that your JAVA_HOME
environment variable is set to a supported JVM installation (JRE 7 or JDK 7).
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.
The Oracle Unified Directory RDBMS implementation relies on the JDBC standard to communicate with the underlying RDBMS. Therefore, you must install the JDBC driver JAR file that corresponds to the RDBMS you are using.
To install a JDBC driver JAR file:
Download the JDBC driver corresponding to the RDBMS database release you are using. Because this use case stores data in Oracle Database 11g, download ojdbc6.jar
from:
http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html
For Oracle Database 11g use ojdbc6.jar
, or for Oracle Database 12c, use ojdbc7.jar
.
Copy the JAR file for the step 1 to the following directory:
OUD_INSTANCE_NAME/OUD/lib
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.
To create the components required for the Oracle Unified Directory proxy to communicate with the RDBMS, perform the tasks described in the following sections:
Section 20.1.3.3, "Creating a Workflow for the RDBMS Entries"
Section 20.1.3.4, "Creating an Access Control Group for the RDBMS Workflow"
Section 20.1.3.5, "Associating the Workflow to a Network Group"
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.
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.
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.
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:
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.
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.
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
You must now map the LDAP attributes to the appropriate columns in the SQL PERSON
and PHONE
tables in the Oracle Database.
To configure the LDAP-SQL mappings in this use case, follow the tasks described in the following sections:
PERSON
and PHONE
TablesIn 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;
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:
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.
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.
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.
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.
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 : +33123456789 ...
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.
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:
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.
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}
).
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 : +33123456789
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.This section describes how to configure communication between a proxy instance and one or more remote LDAP servers.
Note:
For more information about communicating with remote LDAP servers, see Section 12.1.2, "Enabling Communication with a Remote LDAP Server."The topics in this section include:
This section describes how to configure the LDAP server extensions required to communicate with the remote LDAP server. The section covers the following topics:
Section 20.2.1.1, "Viewing the Existing LDAP Server Extensions"
Section 20.2.1.2, "Viewing LDAP Server Extension Properties"
Section 20.2.1.3, "Viewing Advanced LDAP Server Extension Properties"
Section 20.2.1.5, "Modifying the Properties of an LDAP Server Extension"
Section 20.2.1.6, "Modifying the Advanced Properties of an LDAP Server Extension"
Section 20.2.1.7, "Modifying the LDAP Data Source Monitoring Connection Properties"
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.
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
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
Indicate 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 Section 35.5, "Monitoring the Server With LDAP."
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) pool-increment 5 8) pool-initial-size 10 9) pool-max-size 1000 10) pool-max-write 0 11) pool-release-connection-interval 300000 12) pool-use-max-write false 13) proxied-auth-use-v1 false 14) remote-ldap-server-address localhost 15) remote-ldap-server-connect-timeout 10000 16) remote-ldap-server-port 1389 17) remote-ldap-server-read-only false 18) remote-ldap-server-read-timeout 10000 19) remote-ldap-server-ssl-policy never 20) remote-ldap-server-ssl-port 636 21) saturation-precision 5 22) ssl-client-alias - 23) ssl-key-manager-provider - 24) ssl-trust-all false 25) ssl-trust-manager-provider -
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 Section 20.2.1.5, "Modifying the Properties of an LDAP Server Extension."
For information about the monitoring properties, see Section 20.2.1.7, "Modifying the LDAP Data Source Monitoring Connection Properties."
For information about the SSL (security) properties, see Chapter 27, "Configuring Security Between the Proxy and the Data Source."
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.
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 Section 20.2.1.6, "Modifying the Advanced Properties of an LDAP Server Extension."
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 Section 27.2, "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 Appendix B, "Supported Controls and Operations."
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.
The monitoring properties are described in Section 20.2.1.7, "Modifying the LDAP Data Source Monitoring Connection Properties."
The SSL properties are security features. For information about these properties, see Chapter 27, "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
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. This 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 Section 23.6, "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).
This section describes how to configure the LDAP proxy workflow elements required to communicate with the remote LDAP server.
The topics in this section include:
Section 20.2.2.1, "Viewing the Existing Proxy LDAP Workflow Elements"
Section 20.2.2.2, "Viewing the Properties of a Proxy LDAP Workflow Element"
Section 20.2.1.5, "Modifying the Properties of an LDAP Server Extension"
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
.
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
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 Chapter 27, "Configuring Security Between the Proxy and the Data Source."
enabled
Indicates if the workflow is enabled (true
) or not (false
)
ldap-server-extension
The name of the LDAP server extension with which the workflow element is associated
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
.
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.
Notes:
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 Section 24.5, "Configuring RDN Changing," 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 Chapter 27, "Configuring Security Between the Proxy and the Data Source."
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
When an end user executes an authenticated operation, the proxy LDAP workflow element receives the following two distinct operations:
A BIND operation that authenticates the user against the remote server.
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-1 lists the bind modes that are supported by Oracle Unified Directory.
Table 20-1 Supported Bind Modes by Oracle Unified Directory
Mode | Description |
---|---|
|
Use the client credentials to perform the silent bind. |
|
Use the proxy credentials to perform the silent bind. |
For each of the bind modes described in Table 20-1, you can configure additional parameters to tweak the behavior of the server.
For a description of these parameters, see the following sections:
Section 20.2.3.1.1, "Configuring the use-client-identity
Bind Mode"
Section 20.2.3.1.2, "Configuring the use-specific-identity
Bind Mode"
use-client-identity
Bind ModeIf 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 theremote-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 theuse-proxy-auth
property determines whether the control should be added.use-specific-identity
Bind ModeWhen 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 theremote-ldap-server-bind-dn
and remote-ldap-server-bind-password
properties of the proxy LDAP workflow element.