Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition

Chapter 22 Directory Proxy Server Virtualization

This chapter describes how to create virtual data views. Virtual data views transform the source data and present a different view of that data to client applications. Virtual data views include transformed LDAP data views, LDIF data views, join data views, and JDBC data views. For an overview of the features of virtual data views and a description of example use cases, see Chapter 18, Directory Proxy Server Virtualization, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

You cannot use Directory Service Control Center (DSCC) to perform the procedures in this chapter. You must use the command line.

This chapter covers the following topics:

Creating and Configuring LDIF Data Views

An LDIF data view is a simple virtual data view in which an LDIF file is made to look like an LDAP data source. Unlike for LDAP data views, you do not create data sources or data source pools when you set up LDIF data views. Instead, you specify an LDIF file when you create the data view. By default, you cannot write to an LDIF data view. For more information, see Defining Access Control on Virtual Data Views.

For information about creating and configuring LDIF data views, see the following procedures.

To Create an LDIF Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create an LDIF data view.

$ dpconf create-ldif-data-view -h host -p port view-name path-to-ldif-file suffix-dn

(Optional) View the list of LDIF data views.
$ dpconf list-ldif-data-views -h host -p port
The virtual access controls data view is the only default LDIF data view. This data view is generated by the server and enables requests to be routed to virtual access control instructions (ACIs).

To Configure an LDIF Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

View the properties of an LDIF data view.

$ dpconf get-ldif-data-view-prop -h host -p port view-name

An LDIF data view has the following default properties:

alternate-search-base-dn                    :  -  
attr-name-mappings                          :  none  
base-dn                                     :  suffixDN
bind-pwd-attr                               :  userPassword  
contains-shared-entries                     :  false  
custom-distribution-algorithm               :  none  
db-pwd-encryption                           :  clear-text  
description                                 :  -  
distribution-algorithm                      :  none  
dn-join-rule                                :  none  
dn-mapping-attrs                            :  none  
dn-mapping-source-base-dn                   :  none  
excluded-subtrees                           :  -  
filter-join-rule                            :  none  
is-enabled                                  :  true  
is-read-only                                :  false  
is-routable                                 :  true  
ldif-data-source                            :  /path/to/filename.ldif
lexicographic-attrs                         :  all  
lexicographic-lower-bound                   :  none  
lexicographic-upper-bound                   :  none  
non-viewable-attr                           :  none  
non-writable-attr                           :  none  
numeric-attrs                               :  all  
numeric-default-data-view                   :  false  
numeric-lower-bound                         :  none  
numeric-upper-bound                         :  none  
pattern-matching-base-object-search-filter  :  all  
pattern-matching-dn-regular-expression      :  all  
pattern-matching-one-level-search-filter    :  all  
pattern-matching-subtree-search-filter      :  all  
process-bind                                :  -  
replication-role                            :  master  
viewable-attr                               :  all except non-viewable-attr  
writable-attr                               :  all except non-writable-attr

Change one or more of the properties that are listed in Step 1.

$ dpconf set-ldif-data-view-prop -h host -p port view-name property:value \
 [property:value ... ]

For example, to change the source LDIF file for the data view, set the ldif-data-source property.

$ dpconf set-ldif-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \
myLDIFDataView ldif-data-source:/local/files/example.ldif

Defining Access Control on Virtual Data Views

ACIs on virtual data views can be stored in an LDAP directory or in an LDIF file. For information about how virtual ACIs work, see Access Control On Virtual Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

When you create a Directory Proxy Server instance, the following default configuration for virtual access controls is defined:

An LDIF file in which ACIs are stored by default (instance-path/config/access_controls.ldif)
An LDIF data view named virtual access controls

This data view enables Directory Proxy Server to access the ACIs stored in the LDIF file.

To Define a New ACI Storage Repository

If you do not want to use the default ACI configuration described previously, you can define a different storage repository.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create a data view for the repository in which the virtual ACIs will be stored.
- If the ACIs will be stored in an LDAP directory, create an LDAP data source, an LDAP data source pool, and an LDAP data view, as described in Chapter 18, LDAP Data Views.
- If the ACIs will be stored in an LDIF file, create an LDIF data view, as described in Creating and Configuring LDIF Data Views.

Specify the name of the data view created in the previous step as the ACI data view.
$ dpconf set-virtual-aci-prop -h host -p port aci-data-view:data-view-name

If the ACI repository is an LDAP directory, define the credentials required to access the ACI data view.

$ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-dn:bind-dn
$ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-pwd-file:filename

To Configure Virtual Access Controls

Regardless of the ACI repository that you use, you must configure the virtual access controls.

Note –

Only the Proxy Manager can create a pool of ACIs and manage ACIs directly through the ACI data view. If the ACI repository is an LDAP directory, you must modify the schema of that directory to include the aciSource object class and the dpsaci attribute. For more information about customizing the schema, see Extending Directory Server Schema.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create a pool of ACIs in the ACI repository, and set up global ACIs.

For information about global ACIs, see Global ACIs in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition. To set up global ACIs, add an aciSource entry under the view base of the ACI data view. For example:

% ldapmodify -p port -D "cn=proxy manager" -w -
dn: cn=aci-source-name,cn=virtual access controls
changetype: add
objectclass: aciSource
dpsaci: (targetattr="*") (target="ldap:///ou=people,o=virtual") (version 3.0; 
 acl "perm1"; allow(all) groupdn="ldap:///cn=virtualGroup1,o=groups,o=virtual";)
cn: aci-source-name

Configure one or more connection handlers to use this pool of ACIs.

% dpconf set-connection-handler-prop -h host -p port connection-handler \
aci-source:aci-source-name

Add the required ACIs to the data.

To do this, create a virtual entry that contains the ACIs. For example:

% ldapmodify -p port -D "cn=virtual application,ou=application users,dc=com" -w -
dn: ou=people,o=virtual
changetype: modify
add: dpsaci
dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(all) userdn="ldap:///self";)
dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(search, read, compare) 
 userdn ="ldap:///anyone";)

Note –

Any user with the appropriate access rights can add and retrieve virtual ACIs through the data view.

Defining Schema Checking on Virtual Data Views

Generally, for LDAP data views, schema checking is performed by the back-end directory, using the back-end directory's schema. Use the following procedure if you want schema checking to be performed by Directory Proxy Server.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

To normalize requests, particularly the DN, set the use-external-schema property of the server, as follows:

To Define Schema Checking

Indicate that the server instance should use an external schema.

$ dpconf set-server-prop -h host -p port use-external-schema:true

Enable schema checking on the connection handler.

$ dpconf set-connection-handler-prop -h host -p port connection-handler \
 schema-check-enabled:true

Create a data view that exposes cn=schema.

If the external schema is defined in an LDAP directory, create an LDAP data view, as described in Chapter 18, LDAP Data Views, with a view base of cn=schema.

If the external schema is defined in an LDIF file, create an LDIF data view, as described in Creating and Configuring LDIF Data Views with a view base of cn=schema.

Add this data view to the list of data views exposed by the connection handler.

By default, all data views are exposed by the connection handler. If you have defined a custom list of data views that are exposed by the connection handler, add this data view to the list.
$ dpconf set-connection-handler-prop -h host -p port connection-handler \ data-view-routing-custom-list+:data-view-name

Creating and Configuring Join Data Views

A join data view is an aggregation of multiple data views. For information about how a join data view works, see Join Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure join data views, see the following procedures.

To Create a Join Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Identify the primary and secondary data views that will be aggregated to form the join view.

The primary and secondary data views must exist before the join view can be created. The primary and secondary views can be any type of data view, including an LDAP data view, LDIF data view, JDBC data view, or another join data view. Specific properties must be configured on the secondary view to allow it to function as the source for a join view. For more information, see To Configure the Secondary View of a Join View.

Create the join data view.

$ dpconf create-join-data-view -h host -p port view-name primary-view secondary-view \
 suffix-dn

(Optional) View the list of join views to check that your data view has been created successfully.
$ dpconf list-join-data-views -h host -p port

To Configure a Join Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

View the properties of a join data view.

$ dpconf get-join-data-view-prop -h host -p port view-name

The default properties of a join data view are as follows:

allow-heuristic-search                      :  true  
allow-partial-search                        :  false  
alternate-search-base-dn                    :  -  
attr-name-mappings                          :  none  
base-dn                                     :  suffixDN  
contains-shared-entries                     :  false  
custom-distribution-algorithm               :  none  
description                                 :  -  
distribution-algorithm                      :  none  
dn-join-rule                                :  none  
dn-mapping-attrs                            :  none  
dn-mapping-source-base-dn                   :  none  
excluded-subtrees                           :  -  
filter-join-rule                            :  none  
is-enabled                                  :  true  
is-read-only                                :  false  
is-routable                                 :  true  
join-rule-control-enabled                   :  false  
lexicographic-attrs                         :  all  
lexicographic-lower-bound                   :  none  
lexicographic-upper-bound                   :  none  
non-viewable-attr                           :  none  
non-writable-attr                           :  none  
numeric-attrs                               :  all  
numeric-default-data-view                   :  false  
numeric-lower-bound                         :  none  
numeric-upper-bound                         :  none  
pattern-matching-base-dn-regular-expression :  all  
pattern-matching-base-object-search-filter  :  all  
pattern-matching-dn-regular-expression      :  all  
pattern-matching-one-level-search-filter    :  all  
pattern-matching-subtree-search-filter      :  all  
primary-view                                :  primary-view  
process-bind                                :  -  
replication-role                            :  master  
request-grouping-size                       :  5
secondary-view                              :  secondary-view  
viewable-attr                               :  all except non-viewable-attr  
vlv-control-enabled                         :  false  
vlv-control-page-size                       :  1k  
vlv-control-sorting-attr                    :  objectclass  
writable-attr                               :  all except non-writable-attr

Change one or more of the properties that are listed in Step 1.
$ dpconf set-join-data-view-prop -h host -p port view-name property:value \ [property:value ... ]
For example, to change the primary data view of a data source to myLDAPDataView, use the following command:
$ dpconf set-join-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \ myJoinDataView primary-view:myLDAPDataView
If vlv-control-enabled is set to true, Directory Proxy Server uses VLV control in search requests when it contacts the primary data view.

When a join data view is configured, set viewable-attr and writable-attr properties on primary data view and secondary data view.

Setting of these properties helps in splitting the search filters appropriately on primary and secondary data views. Otherwise, there might be discrepancies in search results when search filter contains attributes from secondary data view.

If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

To Configure a Join Data View to Enable Referencing of a Data View by Multiple Join Data Views

Setting join rule configuration information in the join data view makes the data view to be referenced by multiple join data views. To do so, perform the following:

Set join-rule-control-enabled to true on the join data view.
$ dpconf set-join-data-view-prop view-name join-rule-control-enabled:true
After setting join-rule-control-enabled to true, join rule configuration information stored in the join data view is used by the server. If you have a join data view with the join rule configuration information stored in the secondary data view then this information is not used by the server. To have this information used by the server, you will have to manually add the configuration information at the join data view level.

Define a join rule that determines how the secondary view is related to the primary view.

The join rule can be one of the following:
- DN join rule
  $ dpconf set-join-data-view-prop view-name \ dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example
- Filter join rule
  $ dpconf set-join-data-view-prop view-name \ filter-join-rule:uid=\${primary-view-name.uid}
In the above commands, the attribute name is enclosed in ${} when treated as a variable. If you do not use attribute names enclosed in ${}, the attribute names are treated as constants.

If you use bash or ksh in UNIX, the $ character should be escaped by \ in the \${primary-view-name.uid} like constructions whereas no escaping is required on Windows.

To Configure the Secondary View of a Join View

Specific properties must be configured on the secondary data view to allow it to function as the source for a join view. Because the secondary view can be any type of data view, the command you use will depend on the data view type. The following sample commands assume that the secondary view is an LDAP data view. For more information about the properties described here, see Additional Secondary Data View Properties in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Define a join rule that determines how the secondary view is related to the primary view.

Never set the filter-join-rule and dn-join-rule on the primary data view of a join view.

The join rule can be one of the following:
- DN join rule
  $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example
- Filter join rule
  $ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ filter-join-rule:uid=\${primary-view-name.uid}
The configuration for the dn-join-rule and filter-join-rule properties is used by the server only if the join-rule-control-enabled property on the join data view is set to false. Otherwise, if the join-rule-control-enabled property is set to true on the join data view, then the information set on the secondary view will be ignored.

If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.
dpconf add-virtual-transformation secondary-view-name \ write add-attr-value dn uid=\${uid}
Note –
Without setting this rule, addition of entries to join data view would not be possible.

(Optional) Specify whether binds are allowed on the secondary view.

By default, binds are permitted on all data views. If you want to prohibit binds to the secondary data view, run the following command:
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name process-bind:false
For more information about this property, see Handling of Binds in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

(Optional) Specify whether the secondary view contains shared entries.
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ contains-shared-entries:true
For more information about this property, see Handling of Shared Entries in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

Creating and Configuring Coordinator Data Views

The Coordinator data view has an ordered list of data views to coordinate. When the Coordinator data view receives a request, it sends the request to its coordinated data views in the right order, which is defined by the order used in the CLI to specify the coordinated data view. The Coordinator data view sends the request to coordinated data view as defined by the routing policy and in the end returns the result(s) to the client. For more information, see Coordinator Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The Coordinator data view supports the following routing policies:

first-match: stops sending the request at first match
all-candidates: sends the request to all the coordinated data views
mirror: sends all the requests to first coordinated data view but the write requests are sent to all the coordinated data views.

Note –

All the data views coordinated by a coordinator data view must have the same view base identical with the view base of the coordinator data view.

To Create a Coordinator Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Identify the data views that will be aggregated to form the Coordinator data view.

The data views must exist before the Coordinator data view can be created. The data views can be any type of data view, including an LDAP data view, LDIF data view, JDBC data view, or another join data view.

Create the Coordinator data view.

$ dpconf create-coordinator-data-view -h host -p port VIEW_NAME \
COORDINATED_VIEW [COORDINATED_VIEW...] SUFFIX_DN

The following command creates a Coordinator data view, view_com, using two data views.

$ dpconf create-coordinator-data-view -h host -p port view_com \
first_view second_view dc=com

(Optional) View the list of Coordinator data views to check that your data view has been created successfully.
$ dpconf list-coordinator-data-views -h host -p port
In this case, the above command displays view_com.

To Configure a Coordinator Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

View the properties of a Coordinator data view.

$ dpconf get-coordinator-data-view-prop -h host -p port VIEW_NAME

The default properties of a join data view are as follows:

alternate-search-base-dn                       :  ""
attr-name-mappings                             :  none
base-dn                                        :  ""
contains-shared-entries                        :  -
coordinated-data-view                          :  first_view 
coordinated-data-view                          :  second_view
custom-distribution-algorithm                  :  none
description                                    :  -
distribution-algorithm                         :  none
dn-join-rule                                   :  none
dn-mapping-attrs                               :  none
dn-mapping-source-base-dn                      :  none
excluded-subtrees                              :  ""
filter-join-rule                               :  none
is-enabled                                     :  true
is-read-only                                   :  false
is-routable                                    :  true
lexicographic-attrs                            :  all
lexicographic-lower-bound                      :  none
lexicographic-upper-bound                      :  none
non-viewable-attr                              :  none
non-writable-attr                              :  none
numeric-attrs                                  :  all
numeric-default-data-view                      :  false
numeric-lower-bound                            :  none
numeric-upper-bound                            :  none
pattern-matching-base-object-search-filter     :  all
pattern-matching-dn-regular-expression         :  all
pattern-matching-one-level-search-filter       :  all
pattern-matching-subtree-search-filter         :  all
process-bind                                   :  -
replication-role                               :  master
routing-policy                                 :  all-candidates
viewable-attr                                  :  all except non-viewable-attr 
writable-attr                                  :  all except non-writable-attr

For example, the following commands lists the coordinated-data-views property of the specified Coordinator data view.

$ dpconf get-coordinator-data-view-prop VIEW_NAME coordinated-data-view 

coordinated-data-view  :  first_view
coordinated-data-view  :  second_view

Change one or more of the properties that are listed in Step 1.

$ dpconf set-coordinator-data-view-prop -h host -p port VIEW_NAME PROP:VAL \
[PROP:VAL...]

For example, add more coordinated data views to the Coordinator data view using the following command:

$ dpconf set-coordinator-data-view-prop -h host -p port view_com \
coordinated-data-view+:third_view coordinated-data-view+:fouth_view

As per the order of the coordinated data views specified in the above command, the coordinated data views are send in the following order:

$ dpconf get-coordinator-data-view-prop VIEW_NAME coordinated-data-view 

coordinated-data-view  :  first_view
coordinated-data-view  :  second_view 
coordinated-data-view  :  third_view
coordinated-data-view  :  fourth_view

(Optional) Change the routing-policy mode that describe how Coordinator data view sends the requests to coordinated data views.
$ dpconf set-coordinator-data-view-prop -h host -p port view_com \ routing-policy:first-match
For more information, see routing-policy(5dpconf).

If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Creating and Configuring JDBC Data Views

A JDBC data view enables you to make a relational database accessible to LDAP client applications. For information about how JDBC data views work, see JDBC Data Views in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

For information about how to create and configure JDBC data views, see the following procedures.

To Create a JDBC Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create a JDBC data source for the relational database.
$ dpconf create-jdbc-data-source -h host -p port -b db-name -B db-url -J driver-url \ [-J driver-url]... -S driver-class source-name
Currently, only one JDBC data source is supported for each JDBC data view. In other words, you cannot load balance across JDBC data sources. To access multiple JDBC data sources, you can create a data view for each data source, and join them together with a join data view.

The following properties must be set when you create a JDBC data source:

db-name

The name of the relational database, for example, payrolldb.

db-url

The URL to the database, in the form jdbc:vendor:driver://dbhost:dbport.

The db-url is not a complete JDBC database URL, because it does not contain the database name. (The database name is specified by the db-name property.)

You must finish db-url with a / for MySQL, DB2, and Derby databases and with a : for Oracle database.

driver-class

The JDBC driver class, for example org.hsqldb.jdbcDriver.

driver-url

The path to the JDBC driver, for example file:///path/to/hsqldb/lib/hsqldb.jar.

The driver-url property is multivalued. Hence, driver-url can support multiple JAR files for the JDBC driver to ensure connectivity to the JDBC source on different platforms.

If a 3rd party JDBC driver, which is other than the JDBC driver provided by the DB Vendor, is used to connect to the RDBMS back-end, set the db-vendor property. For more information about the db-vendor property, see db-vendor(5dpconf)

Create a JDBC data source pool.

$ dpconf create-jdbc-data-source-pool -h host -p port pool-name

Attach the JDBC data source to the JDBC data source pool.

$ dpconf attach-jdbc-data-source -h host -p port pool-name source-name

Create a JDBC data view.

$ dpconf create-jdbc-data-view -h host -p port view-name pool-name suffix-DN

(Optional) View the list of JDBC data views to check that your data view has been created successfully.
$ dpconf list-jdbc-data-views -h host -p port

To Configure a JDBC Data View

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

View the properties of a JDBC data view.

$ dpconf get-jdbc-data-view-prop -h host -p port view-name

The default properties of a JDBC data view are as follows:

alternate-search-base-dn                    :  -
attr-name-mappings                          :  none
base-dn                                     :  o=sql1
contains-shared-entries                     :  -
description                                 :  -
distribution-algorithm                      :  -
dn-join-rule                                :  -
dn-mapping-attrs                            :  none
dn-mapping-source-base-dn                   :  none
excluded-subtrees                           :  -
filter-join-rule                            :  -
is-enabled                                  :  true
is-read-only                                :  false
is-routable                                 :  true
jdbc-attr-date-format                       :  yyyy-MM-dd
jdbc-attr-time-format                       :  hh:mm:ss
jdbc-attr-timestamp-format                  :  yyyy-MM-dd hh:mm:ss
jdbc-data-source-pool                       :  pool-name
lexicographic-attrs                         :  all
lexicographic-lower-bound                   :  none
lexicographic-upper-bound                   :  none
non-viewable-attr                           :  -
non-writable-attr                           :  -
numeric-attrs                               :  all
numeric-default-data-view                   :  false
numeric-lower-bound                         :  none
numeric-upper-bound                         :  none
pattern-matching-base-object-search-filter  :  all
pattern-matching-dn-regular-expression      :  all
pattern-matching-one-level-search-filter    :  all
pattern-matching-subtree-search-filter      :  all
process-bind                                :  -
replication-role                            :  master
viewable-attr                               :  all except non-viewable-attr
writable-attr                               :  all except non-writable-attr

Change one or more of the properties that are listed in Step 1.

$ dpconf set-jdbc-data-view-prop -h host -p port view-name property:value \
 [property:value ... ]

(Optional) In addition to the ISO format, you can set JDBC attributes of type date, time, and timestamp attributes in all of the following formats as well.

Following lists the components that constitutes date and time:

Letter      Date or Time Component   Examples
G           Era designator           AD
y           Year                     1996; 96
M           Month in year            July; Jul; 07
w           Week in year             27
W           Week in month            2
D           Day in year              189
d           Day in month             10
F           Day of week in month     2
E           Day in week              Tuesday; Tue
a           Am/pm marker             PM
H           Hour in day (0-23)       0
k           Hour in day (1-24)       24
K           Hour in am/pm (0-11)     0
h           Hour in am/pm (1-12)     12
m           Minute in hour           30
s           Second in minute         55
S           Millisecond              978
z           Time zone                Pacific Standard Time; PST; GMT-08:00
Z           Time zone                -0800

The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone.

Date and Time Pattern                Result
"yyyy.MM.dd G 'at' HH:mm:ss z"       2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy"                   Wed, Jul 4, '01
"h:mm a"                             12:08 PM
"hh 'o''clock' a, zzzz"              12 o'clock PM, Pacific Daylight Time
"K:mm a, z"                          0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa"       02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z"         Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ"                      010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ"         2001-07-04T12:08:56.235-0700

To Configure JDBC Tables, Attributes, and Object Classes

When you configure a JDBC data view, you must also configure the following objects:

JDBC object class. Maps one or more JDBC tables to an LDAP object class.
JDBC table. Defined for each relational database table.
JDBC attribute. Defines an LDAP attribute from a specified column in a JDBC table.

Create a JDBC table for each table in the relational database.
% dpconf create-jdbc-table jdbc-table-name db-table
The name of the db-table is case sensitive. Make sure that you use the identical case that is used in the relational database, otherwise operations that target that table might fail.

Create a JDBC attribute for each column in each relational database table.
% dpconf add-jdbc-attr table-name attr-name sql-column
Creating a JDBC attribute maps the table column to an LDAP attribute.

(Optional) If the column in the relational database is case sensitive, change the LDAP syntax of the JDBC attribute.
% dpconf set-jdbc-attr-prop table-name attr-name ldap-syntax:ces
The value of ldap-syntax is cis by default. This implies that the jdbc-attr is case insensitive. Change the value to ces if your relational database is case sensitive.

Certain relational databases, such as Oracle and DB2, are case sensitive by default. LDAP is case insensitive by default. When Directory Proxy Server detects that a column of the relational database table is case sensitive, an ldapsearch query with the corresponding attribute in the filter is translated into a SQL query using the function UPPER.

For example, the query ldapsearch -b "dc=mysuffix" "(attr=abc)" is translated into the following SQL query:
SELECT * FROM mytable WHERE (UPPER(attr)='ABC')
By default, this type of query is not indexed. Queries of this nature can therefore have a substantial performance impact.

You can alleviate the performance impact in two ways:
- By setting the ldap-syntax property of the jdbc-attr to ces.
- By creating an index with the function UPPER for each jdbc-attr that might be used in an LDAP filter.
Note –
If your relational database is not case sensitive, use ldap-syntax with the default value, that is, cis. ldap-syntax:ces is not supported with the case insensitive databases.

Create a JDBC object class for the LDAP relational database table.
% dpconf create-jdbc-object-class view-name objectclass primary-table \ [secondary-table... ] DN-pattern
Creating a JDBC object class essentially specifies an LDAP object class with which these tables will be associated. The JDBC object class also specifies the primary table and the secondary tables, if they exist.

When you create a JDBC object class, you specify a DN pattern. DN pattern describes which attributes are to be used to construct DN of the entry. For example, when you specify DN pattern as uid then the DN of the entry is constructed using attribute uid and view base of the data view. For example, uid=bjensen,ou=people,dc=example,dc=com. The DN pattern can constitute multiple attributes. In that case, attributes should be separated by , (comma). For example, if DN pattern is specified as uid,country, DN of the entry returned by the data view is uid=bjensen,country=America,ou=people,dc=example,dc=com.

When data source contains duplicate entries and the duplicate entries are not required, set perform-distinct-select to true using the following command:
% dpconf set-jdbc-object-class-prop view-name objectclass perform-distinct-select:true
All the subtree components defined in the DN pattern of JDBC object class should have a JDBC object class defined for them. For example, if there is a DN pattern uid,ou in a JDBC object class, there should be a JDBC object class definition with a DN pattern ou. This is necessary for Directory Proxy Server to construct a properly structured DIT. Otherwise, the subtree with values like ou=xxx,base-DN would not be returned in the search results.

If a secondary table exists, define the join rule between the primary table and the secondary table.
% dpconf set-jdbc-table-prop secondary-table-name filter-join-rule:join-rule
A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table. How you define the relationships between the primary and secondary tables of an object class is important. For more information, see Defining Relationships Between JDBC Tables.

Specify the super class for the JDBC object class.
% dpconf set-jdbc-object-class-prop view-name objectclass super-class:value
The super class indicates the LDAP object class from which the JDBC object class inherits.

Defining Relationships Between JDBC Tables

In the simplest case, a JDBC object class contains only a single (primary) table. There is no secondary table, and thus no need to define relationships between tables.

If the object class contains more than one table, the relationships between these tables must be clearly defined. The relationships between tables are always defined on the secondary table. The following properties of a secondary table enable you to define these relationships:

is-single-row-table specifies that an LDAP entry has only one matching row in the table.
contains-shared-entries specifies that a row in the secondary table is used by more than one row in the primary table.
filter-join-rule indicates how an entry should be retrieved from the secondary table based on something in the primary table.

The following examples illustrate how the filter join rule is defined, based on the values of the first two properties. These examples assume that the object class has one primary table and one secondary table.

Example 22–1 `is-single-row-table:true` and `contains-shared-entries:true`

These are the default values of these properties. In this case, the relationship between the primary and secondary tables is n->1, that is, n rows in the primary table reference one shared row in the secondary table.

In the relational database, a foreign key (FK) is defined in the primary table, and points to a column in the secondary table.

Take, for example, an organization in which several employees can share the same manager. Two relational database tables are defined, with the following structure:

primary table : EMPLOYEE [ID, NAME, FK_MANAGER_ID]
secondary table : MANAGER  [ID, NAME]

The following object class and attributes are defined:

object-class : employee
attr : name (from primary EMPLOYEE.NAME)
attr : manager (from secondary MANAGER.NAME)

The following filter join rule is defined in the secondary table:

ID=\${EMPLOYEE.FK_MANAGER_ID}"

In case of multiple secondary tables, you must configure filter-join-rule on each secondary table. For more information on how to configure filter-join-rule for multiple secondary tables, see the Step 12.

With this configuration, the following behavior occurs for LDAP operations:

Adding an employee entry. If the manager in the employee entry does not exist in the table, a new row is created. If the manager does exist, an existing row is used.
Replacing the value of the “manager” attribute in an entry. The value of the row MANAGER.NAME is changed.
Deleting an employee entry. The row in the secondary table is not deleted because the manager entries are shared.
Deleting the “manager” attribute from an entry. The row in the secondary table is deleted and the foreign key (EMPLOYEE.FK_MANAGER_ID) is set to NULL.

If an attribute is deleted, the value of the attribute is set to NULL. But if the attribute is defined as a NOT NULL attribute in the table definition, the deletion is not possible.

Example 22–2 `is-single-row-table:true` and `contains-shared-entries:false`

In this case, the relationship between the primary and secondary tables is 1->1 or 1<-1, that is, one row in the primary table is referenced by one row in the secondary table.

In the relational database, the foreign key (FK) might be defined in the primary table, or in the secondary table.

Take, for example, an organization in which the UID of employees is stored in one table, and the surname of employees is stored in a second table. Two relational database tables are defined, with the following structure:

primary table : UID [ID, VALUE, FK_SN_ID]
secondary table : SN [ID, VALUE]

The following object class and attributes are defined:

object-class : employee
attr : uid (from primary UID.VALUE)
attr : sn (from secondary ID.VALUE)

The following filter join rule is defined in the secondary table:

ID=\${UID.FK_SN_ID}

You can use it in the following manner using the dpconf command:

dpconf set-jdbc-table-prop SN filter-join-rule:ID=\${UID.FK_SN_ID}

This configuration could be the other way around, with the foreign key FK_UID_ID stored in the secondary table, and pointing to UID.ID.

Example 22–3 `is-single-row-table:false` and `contains-shared-entries:false`

In this case, the relationship between the primary and secondary tables is 1->n, that is, one row in the primary table is referenced by n rows in the secondary table. This example illustrates the case of multi-valued attributes. A multi-valued attribute is represented as a set of rows in the secondary table, with one row per attribute value.

In the relational database, the foreign key is defined in the secondary table, and points to a column in the primary table.

Take, for example, an organization in which an employee can have several telephone numbers. Two relational database tables are defined, with the following structure:

primary table : EMPLOYEE [ID, NAME]
secondary table : PHONE [ID, VALUE, USER_ID]

The following object class and attributes are defined:

object-class : employee
attr : cn (from primary EMPLOYEE.NAME)
attr : telephoneNumber (from secondary PHONE.VALUE)

The following filter join rule is defined in the secondary table:

USER_ID=\${EMPLOYEE.ID}

Example 22–4 `is-single-row-table:false` and `contains-shared-entries:true`

This case is currently unsupported in Directory Proxy Server.

Sample Virtual Configurations

The following section provides two sample configurations. These configurations illustrate the main features of a virtual directory, and indicate how these features are configured.

Joining an LDAP Directory and a MySQL Database

The procedures in this section describe a sample virtual configuration that joins an LDAP directory and a MySQL database. The LDAP directory is the primary data source, that contains most of the user information. The MySQL database contains additional information about the users. The resulting configuration is illustrated in the following figure.

Figure 22–1 Sample Virtual Configuration

Figure shows join data view comprising LDAP data view
and JDBC data view

You can use the sample data provided in install-path/resources/ldif/Example.ldif to duplicate this example, or you can substitute the sample data with your own data.

This configuration can be broken into three sections:

Configuring and testing the LDAP data view
Configuring and testing the JDBC data view
Configuring and testing the join data view

For simplicity, all the commands in this section assume that the Directory Proxy Server is running on the local host in /local/dps. The commands also assume that the following environment variables have been set:

DIR_PROXY_PORT: 1389
LDAP_ADMIN_PWF: pwd.txt, a file containing the administrator password.
DIRSERV_PORT: 4389
LDAP_ADMIN_USER: cn=Directory Manager

Configuring and Testing the LDAP Data View

To Configure the LDAP Data View

Before You Begin

The tasks in this section assume the following information:

A Directory Server instance is running on host1, on port 4389.
Data in the Directory Server is stored under the suffix dc=example,dc=com. To duplicate this example, create a Directory Server instance, create the suffix dc=example,dc=com, and import the sample data in install-path/resources/ldif/Example.ldif.

Create an LDAP data source named myds1 for the Directory Server instance.
% dpconf create-ldap-data-source myds1 host1:4389

Enable the data source, and allow write operations to the data source.

% dpconf set-ldap-data-source-prop myds1 is-enabled:true is-read-only:false

Create an LDAP data source pool named myds1-pool.

% dpconf create-ldap-data-source-pool myds1-pool

Attach the LDAP data source to the LDAP data source pool.
% dpconf attach-ldap-data-source myds1-pool myds1

Specify that the data source should receive 100% of the bind, add, search, and modify operations from that data source pool.

% dpconf set-attached-ldap-data-source-prop myds1-pool myds1 add-weight:100 \
 bind-weight:100 modify-weight:100 search-weight:100

Create an LDAP data view for the data source pool, named myds1–view, with a base DN of dc=example,dc=com.
% dpconf create-ldap-data-view myds1-view myds1-pool dc=example,dc=com

To Test the LDAP Data View

As a user under dc=example,dc=com, search all entries in the LDAP data source to verify that you can read from the data view.
% ldapsearch -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery \ -b dc=example,dc=com "objectclass=*"
Note –
You must use the credentials of a user under dc=example,dc=com. If you want to use cn=Directory Manager, you must define a data view to handle that DN.

As a user under dc=example,dc=com, modify the userPassword attribute to verify that you can write to the data view.
% ldapmodify -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery dn: uid=kvaughan,ou=people,dc=example,dc=com changetype: modify replace: userPassword userPassword: myNewPassword
Note –
A default ACI in Directory Server allows users to modify their own passwords.

Configuring and Testing the JDBC Data View

The following tasks assume that a MySQL database is installed, running and populated with data, and that the MySQL database has the following characteristics:

Database name : sample_sql
Database URL : host2.example.com:3306/
JDBC driver URL : file:/net/host2.example/local/mysql/lib/jdbc.jar
Driver class : com.mysql.jdbc.Driver
Database user : root
Database password file : mysqlpwd.txt

The following table describes the tables in the database, and their composite fields. You need this information to set up the JDBC data view.

MySQL Table	Fields
`EMPLOYEE`	`ID`, `SURNAME`,`PASSWORD`, `ROOM`, `COUNTRY_ID`
`COUNTRY`	`ID`, `NAME`
`PHONE`	`USER_ID`, `NUMBER`

To Configure the JDBC Data View

Create a JDBC data source named mysql1 for the SQL database.
% dpconf create-jdbc-data-source -b sample_sql \ -B jdbc:mysql://host2.example.com:3306/ \ -J file:/net/host2.example/local/mysql/lib/jdbc.jar \ -S com.mysql.jdbc.Driver mysql1
Note –
You can set the number of connections for JDBC data source using the num-connection-incr(5dpconf), num-connection-init(5dpconf), and num-connection-limit(5dpconf) JDBC data source properties.

Specify the user name and password file for the SQL database.
% dpconf set-jdbc-data-source-prop mysql1 db-pwd:sqlpwd db-user:rootUser
The sqlpwd and rootUser are the password and username of the authenticating user and these credentials are stored in the database. You must configure the proxy server with username and password when configuring a JDBC data source.

The db-vendor property of the JDBC data source should be set using set-jdbc-data-source-prop if a third party JDBC driver, which is other than the one provided by DB Vendor, is used to connect to the RDBMS back-end. This data is used to construct vendor specific SQL statements, whenever possible, to improve performance. For more information, see db-vendor(5dpconf).

Restart the proxy server.
% dpadm restart /local/dps

Enable the data source, and allow write operations to the data source.

% dpconf set-jdbc-data-source-prop mysql1 is-enabled:true is-read-only:false

(Optional) Set monitoring-inactivity-timeout, monitoring-interval, and monitoring-mode for better monitoring of the open connections and data sources. .

For more information, see monitoring-inactivity-timeout(5dpconf), monitoring-interval(5dpconf), and monitoring-mode(5dpconf)

Create a JDBC data source pool named mysql1–pool.
% dpconf create-jdbc-data-source-pool mysql1-pool

Attach the JDBC data source to the data source pool.
% dpconf attach-jdbc-data-source mysql1-pool mysql1

Create a JDBC data view for the data source pool, named myjdbc1–view, with a base DN of o=sql.
% dpconf create-jdbc-data-view mysql1-view mysql1-pool o=sql

Create a JDBC table for each table in the MySQL database.
% dpconf create-jdbc-table employee1 EMPLOYEE % dpconf create-jdbc-table country1 COUNTRY % dpconf create-jdbc-table phone1 PHONE
The name of the table in the SQL database is case sensitive. Make sure that you use the same case that is used in the SQL database.

Create a JDBC attribute for each column in each table.

Creating a JDBC attribute maps the MySQL column to an LDAP attribute.

% dpconf add-jdbc-attr employee1 uid ID
% dpconf add-jdbc-attr employee1 sn SURNAME
% dpconf add-jdbc-attr employee1 userPassword PASSWORD
% dpconf add-jdbc-attr employee1 roomNumber ROOM
% dpconf add-jdbc-attr phone1 telephoneNumber NUMBER
% dpconf add-jdbc-attr country1 countryName NAME

It is not necessary to create JDBC attributes for the phone1 user_id and country1 id columns, because these columns only contain the values that are present in EMPLOYEE.ID for which an LDAP attribute uid is already created.

Create a JDBC object class for the LDAP person object class.

In this step, the employee1 table is identified as the primary table, and the country1 and phone1 tables are identified as secondary tables. The creation of a JDBC object class also requires a DN. In this example, the DN is constructed from the uid attribute and the base DN of the data view.
% dpconf create-jdbc-object-class mysql1-view person employee1 country1 phone1 uid

Define the join rules between the primary table and the secondary tables.

A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table.
% dpconf set-jdbc-table-prop country1 filter-join-rule:ID=\${EMPLOYEE.COUNTRY_ID} % dpconf set-jdbc-table-prop phone1 filter-join-rule:USER_ID=\${EMPLOYEE.ID}

Specify the super class for the JDBC object class.

The super class indicates the LDAP object class from which the JDBC object class inherits attributes.
% dpconf set-jdbc-object-class-prop mysql1-view person super-class:top

To Create the Required ACIs

Before you can test the JDBC data view, you must enable write access to the data view by configuring ACIs. By default, write access to non-LDAP data views is denied. For the purposes of this example, it is sufficient to add one global ACI that allows users to modify their own passwords.

As the Proxy Manager, add a pool of ACIs to the JDBC data source and add a global ACI that allows users to modify their own entries.

% ldapmodify -p 1389 -D "cn=proxy manager" -w password
dn: cn=mysql1,cn=virtual access controls
changetype: add
objectclass: acisource
dpsaci: (targetattr="*") (target = "ldap:///o=sql") 
(version 3.0; acl "enable all access for all users "; allow(all) 
userdn="ldap:///uid=kvaughan,o=sql";)
cn: mysql1

Create a connection handler to handle connections to the o=sql domain.
% dpconf create-connection-handler mysql1-handler

Enable the connection handler and configure it to handle all binds from users in the o=sql domain.

% dpconf set-connection-handler-prop mysql1-handler is-enabled:true \
 bind-dn-filters:"uid=.*,o=sql"

Configure the connection handler to use the pool of ACIs added previously.
% dpconf set-connection-handler-prop mysql1-handler aci-source:mysql1

To Test the JDBC Data View

As a user under o=sql, search the JDBC data source to verify that you can read from the data view.
% ldapsearch -p 1389 -D "uid=kvaughan,o=sql" -w mypwd -b o=sql "objectclass=*"
Note –
You must use the credentials of a user under o=sql.

As a user under o=sql, modify the userPassword attribute to verify that you can write to the data view.

% ldapmodify -p 1389 -D "uid=kvaughan,o=sql" -w mypwd
dn: uid=kvaughan,o=sql
changetype: modify
replace: userPassword
userPassword: myNewpwd

Creating and Testing the Join Data View

To Create the Join Data View

Create a join data view named myjoin1–view.

Specifying the LDAP data view as the primary data view, and the JDBC data view as the secondary data view.
% dpconf create-join-data-view myjoin1-view myds1-view mysql1-view o=join

Define a join rule on the secondary data view.

The following join rule specifies that the uid attribute of entries from the secondary data view should match the uid attribute of entries from the primary data view.
% dpconf set-jdbc-data-view-prop mysql1-view filter-join-rule:uid=\${myds1-view.uid}

If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.
dpconf add-virtual-transformation secondary-view-name \ write add-attr-value dn uid=\${uid}
Note –
Without setting this rule, addition of entries to join data view would not be possible.

Define the set of attributes that can be read from and written to the primary data view through a join data view.

% dpconf set-ldap-data-view-prop myds1-view viewable-attr:dn \
viewable-attr:cn viewable-attr:sn viewable-attr:givenName \
viewable-attr:objectClass viewable-attr:ou viewable-attr:l \
viewable-attr:uid viewable-attr:mail viewable-attr:telephoneNumber \
viewable-attr:facsimileTelephoneNumber viewable-attr:roomNumber \
viewable-attr:userPassword
% dpconf set-ldap-data-view-prop myds1-view writable-attr:dn \
writable-attr:cn writable-attr:sn writable-attr:givenName \
writable-attr:objectClass writable-attr:ou writable-attr:l \
writable-attr:uid writable-attr:mail writable-attr:telephoneNumber \
 writable-attr:facsimileTelephoneNumber writable-attr:roomNumber \
writable-attr:userPassword

These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the LDAP data view directly.

Define the set of attributes that can be read from and written to the secondary data view through a join data view.

% dpconf set-jdbc-data-view-prop mysql1-view viewable-attr:dn \
 viewable-attr:objectclass viewable-attr:sn viewable-attr:roomNumber \
 viewable-attr:userpassword viewable-attr:jobtitle viewable-attr:countryName \
 viewable-attr:telephoneNumber
% dpconf set-jdbc-data-view-prop mysql1-view writable-attr:dn \
writable-attr:objectclass writable-attr:sn writable-attr:roomNumber \
writable-attr:userpassword writable-attr:jobtitle \
writable-attr:countryName writable-attr:telephoneNumber

These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the JDBC data view directly.

To Create the Required ACIs

As the proxy manager, add a global ACI that allows anonymous access to the join data view.

% ldapmodify -p 1389 -D "cn=proxy manager" -w password
dn: cn=myjoin1,cn=virtual access controls
changetype: add
objectclass: acisource
dpsaci: (targetattr="*") (target = "ldap:///o=join") 
(version 3.0; acl "anonymous_access"; allow(all) userdn="ldap:///anyone";)
cn: myjoin1

Configure the connection handler to use the pool of ACIs added previously.

% dpconf set-connection-handler-prop default-connection-handler aci-source:myjoin1

To Test the Join Data View

As an anonymous user, search the join data view.

In this step, we search Kirsten Vaughan's entry to see whether data from both join views is retrieved.
% ldapsearch -p 1389 -b o=join "uid=kvaughan"
Note that the returned entry includes the attributes from both the LDAP data view and the JDBC data view.

As a user under o=join, modify the userPassword attribute to verify that you can write to the join data view.

% ldapmodify -p 1389
dn: uid=kvaughan,ou=people,o=join
changetype: modify
replace: userPassword
userPassword: myPassword

Joining Multiple Disparate Data Sources

This configuration describes an organization, Example.com, whose specific directory service requirements are met by some of the features of a virtual directory.

Data Storage Scenario

Example.com stores organizational data in multiple disparate data sources. For legacy reasons, user data is spread across an LDAP directory, a flat LDIF file, and an SQL database. The HR department stores user data in an LDAP directory, with a base DN of o=example.com. The Payroll department stores data in an SQL database. Administrative data such as departments and building numbers is stored by the administration department in an LDIF file, with a base DN of dc=example,dc=com.

In addition, Example.com has acquired a company named Company22. Company 22 also stores its user data in an LDAP directory, with a base DN of dc=company22,dc=com.

The following diagram provides a high level view of how Example.com's user data is stored.

Figure 22–2 Data Storage In Disparate Sources

Figure shows how Example.com's user data is stored in
disparate data sources

Client Application Requirements

Example.com has several LDAP client applications that require access to the data stored in the disparate data sources. The requirements of the client applications are not all the same. Different views of the data are required. In some cases, the clients require the data to be aggregated. In addition, some client applications require access to Company22's user data so that these new employees of Example.com can be administered along with the old employees.

The following diagram provides a high level view of Example.com's client application requirements.

Figure 22–3 Client Application Requirements

Figure shows the requirements of Example.com's LDAP applications

The following sections walk you through sufficient configuration Directory Proxy Server data views to meet the client application requirements described in this sample scenario. For information about how data views work, see Chapter 17, Directory Proxy Server Distribution, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition and Chapter 18, Directory Proxy Server Virtualization, in Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

The configuration of the sample scenario is divided into the following sections:

Aggregate Data From the HR LDAP Directory and the Administration LDIF File

The HR department stores information such as employee names, job start data, and job level. The administration department stores additional data such as building codes and office numbers. The client application that handles the HR data requires access to the combined data from both sources. Both data sources have a common attribute, the employeeNumber that exists in each entry.

The following diagram illustrates the requirements of the client application.

Figure 22–4 Aggregation of Data From LDAP Directory and LDIF File

Figure shows a join view of an LDAP directory and an
LDIF file

To fulfill this application requirement, a data view is created for the payroll directory and for the administration LDIF file. These two data views are then joined to provide access to the aggregated data. This common attribute enables Directory Proxy Server to aggregate the data for each user.

For simplicity, the commands used in this section assume the following information:

A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF.
The payroll LDAP directory runs on a host named payrollHost, on port 2389.
The LDIF file used to store the administration data is named example.ldif.

To obtain the complete syntax of each command, run the command without any options. For example:

$ dpconf create-ldap-data-view
Operands are missing
Usage: dpconf create-ldap-data-view VIEW_NAME POOL_NAME SUFFIX_DN

Create and Enable an LDAP Data View for the Payroll Directory

Create an LDAP data source for the payroll directory.

$ dpconf create-ldap-data-source payroll-directory payrollHost:2389

Create an LDAP data source pool for the payroll directory.
$ dpconf create-ldap-data-source-pool payroll-pool

Attach the payroll data source to the data source pool.

$ dpconf attach-ldap-data-source payroll-pool payroll-directory

Configure the weights of the attached data source.

$ dpconf set-attached-ldap-data-source-prop -h payrollHost -p 2389 \
payroll-pool payroll-directory add-weight:2 \
bind-weight:2 compare-weight:2 delete-weight:2 \
modify-dn-weight:2 modify-weight:2 search-weight:2

Create an LDAP data view for the payroll directory.

$ dpconf create-ldap-data-view payroll-view payroll-pool o=example.com

Enable the LDAP data view so that client requests can be routed to this data view.
$ dpconf set-ldap-data-view-prop payroll-view is-enabled:true

Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS

Create and Enable an LDIF Data View for the Administration Data

Create an LDIF data view for the administration data.

$ dpconf create-ldif-data-view admin-view example.ldif dc=example,dc=com

Enable the LDIF data view for the administration data.

$ dpconf set-ldif-data-view-prop admin-view is-enabled:true

Specify that the administrator view contains entries that are used by more than one entry in the payroll view.
$ dpconf set-ldif-data-view-prop admin-view contains-shared-entries:true
When this property is set to TRUE, deleting an entry in the payroll data view will not result in the deletion of the shared entry in the administrator data view. Adding an entry to the payroll data view will only add the entry to the secondary data view if it does not already exist.

Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS

Join the Payroll Data View and the Administrator Data View

Create a filter join rule on the administrator data view that specifies how the data should be aggregated.

The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.
$ dpconf set-ldif-data-view-prop admin-view \ filter-join-rule:employeeNumber=\${payroll-view.employeeNumber}

Create a join data view that aggregates the two data views.

For the join data view, the organization uses the suffix DN dc=example,dc=com.
$ dpconf create-join-data-view example-join-view payroll-view admin-view \ dc=example,dc=com

Add Data From Company 22 to Example.Com's DIT by Renaming the DN

The user data for Company 22 is stored under the DN dc=company22,dc=com. While Example.com wants to keep this user data separate in most cases, one client application needs to administer Company 22 employees along with the rest of the Example.com employees. This client application requires Company 22's user data to look like Example.com data.

The following diagram illustrates the requirements of the client application.

Figure 22–5 DN Renaming

Figure shows rename a DN to add data to a DIT

To fulfill this application requirement, a data view with a virtual DN of dc=example,dc=com is created for the Company 22's directory.

For simplicity, the commands used in this section assume the following information:

A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF.
The Company 22 LDAP directory runs on a host named company22Host, on port 2389.

Create a Data View For Company 22's Directory With a Virtual DN

Create an LDAP data source for Company 22's directory.

$ dpconf create-ldap-data-source company22-directory company22Host:2389

Create an LDAP data source pool for Company 22's directory.
$ dpconf create-ldap-data-source-pool company22-pool

Attach Company 22's data source to the data source pool.

$ dpconf attach-ldap-data-source company22-pool company22-directory

Configure the weights of the attached data source.

$ dpconf set-attached-ldap-data-source-prop -p 2389 \
company22-pool company22-directory add-weight:2 \
bind-weight:2 compare-weight:2 delete-weight:2 \
modify-dn-weight:2 modify-weight:2 search-weight:2

Create an LDAP data view for Company 22's directory with a virtual DN of dc=example,dc=com.
$ dpconf create-ldap-data-view company22-view company22-pool dc=example,dc=com

Instruct Directory Proxy Server to map this virtual DN to the real DN that is in Company 22's directory.
$ dpconf set-ldap-data-view-prop company22-view \ dn-mapping-source-base-dn:dc=company22,dc=com

Enable the LDAP data view for Company 22's directory so that client requests can be routed to this data view.
$ dpconf set-ldap-data-view-prop company22-view is-enabled:true

Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS

Add Company 22's Data to the HR Data

The HR department requires an aggregated view of the HR data for Example.com and the newly acquired Company 22. The following diagram illustrates the requirements of the global HR application.

Figure 22–6 Aggregation of Data From Join Data View and LDAP Data View

Figure shows a complex join view of an LDAP directory
and another join view

Join the Example Join Data View and the Company 22 Data View

Create a filter join rule on the Company 22 data view that specifies how the data should be aggregated.

The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.
$ dpconf set-ldif-data-view-prop company22-view \ filter-join-rule:employeeNumber=\${example-join-view.employeeNumber}

Create a join data view that aggregates Company 22's data view and Example.com's join data view.

$ dpconf create-join-data-view global-join-view example-join-view \
company22-view dc=example,dc=com

Enable LDAP Clients to Access the Payroll Data in an SQL Database

Example.com's payroll department stores salary data in an SQL database. The database has two tables, and employee table and a salary table. Example.com has an LDAP client application that requires access to that data. The client application requires the SQL data to look like LDAP data.

The following diagram illustrates the requirements of the client application.

Figure 22–7 JDBC Dataview Providing Access to an SQL Database

Figure shows JDBC data view providing access to an SQL
database

To fulfill this application requirement, a JDBC data view is created that maps columns in the SQL tables to LDAP attributes.

For simplicity, the commands used in this section assume the following information:

A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF.
The SQL database is up and running.
The JAVA_HOME variable has been set to the correct Java path.
The password to the SQL database is myPassword stored in the myPasswordFile file.

Create a JDBC Data View For Example.com's Payroll Database

Create a JDBC data source for the payroll database.

$ dpconf create-jdbc-data-source -b payrollsqldb \
  -B jdbc:payrollsqldb:payrollsql://localhost/ \
  -J file://payrollsqldb.jar \
  -S org.payrollsqldb.jdbcDriver payroll-src

Configure the JDBC data source with the properties of the SQL database.

$ dpconf set-jdbc-data-source-prop payroll-src \
  db-user:proxy db-pwd-file:password-file-location/myPasswordFile

Enable the JDBC data source.

$ dpconf set-jdbc-data-source-prop payroll-src is-enabled:true

Create a JDBC data source pool for the payroll database.
$ dpconf create-jdbc-data-source-pool payroll-pool

Attach the payroll data source to the data source pool.

$ dpconf attach-jdbc-data-source payroll-pool payroll-src

Create a JDBC data view for the payroll database, with a virtual DN of o=payroll.
$ dpconf create-jdbc-data-view payroll-view payroll-pool o=payroll

Create a JDBC table for each table in the SQL database.

$ dpconf create-jdbc-table jdbc-employee employee
$ dpconf create-jdbc-table jdbc-salary salary

Add a JDBC attribute for each column in the SQL tables.

$ dpconf add-jdbc-attr jdbc-employee eid employee_id
$ dpconf add-jdbc-attr jdbc-employee first firstname
$ dpconf add-jdbc-attr jdbc-employee last lastname
$ dpconf add-jdbc-attr jdbc-employee description description
$ dpconf add-jdbc-attr jdbc-employee spouse spousename
$ dpconf add-jdbc-attr jdbc-salary salary salary
$ dpconf add-jdbc-attr jdbc-salary social ssn

Specify which attributes can be viewed and which can be written, through the JDBC data view.

$ dpconf set-jdbc-data-view-prop payroll-view \
 viewable-attr:eid \
 viewable-attr:first \
 viewable-attr:last \
 viewable-attr:desc \
 viewable-attr:spouse \
 viewable-attr:salary \
 viewable-attr:social 
 $ dpconf set-jdbc-data-view-prop payroll-view \
 writable-attr:eid \
 writable-attr:first \
 writable-attr:last \
 writable-attr:description \
 writable-attr:spouse \
 writable-attr:salary \
writable-attr:social

Create a JDBC object class that maps to an LDAP object class.

The following command creates an object class that maps to the LDAP person object class. The object class specifies that the employee table should be used as the primary table, and that the salary table should be used as the secondary table. The eid attribute should be used to construct the DN.
$ dpconf create-jdbc-object-class payroll-view \ person jdbc-employee jdbc-salary eid

Create a filter join rule on the secondary table that specifies how data from the secondary table should be linked to data from the primary table.

The following join rule specifies that data should be joined based on the employee_id attribute.
$ dpconf set-jdbc-table-prop jdbc-salary \ filter-join-rule:employee_id=\${employee.employee_id}

Create a super class on the JDBC object class.

$ dpconf set-jdbc-object-class-prop payroll-view person super-class:extensibleObject

Add Virtual Access Control

Access control on LDAP directories is handled by defining ACIs in the directories themselves. When data sources are accessed through virtual data views, ACIs must be defined that apply only to the data viewed through these data views.

Any access that goes through Directory Proxy Server is controlled by a connection handler. For information about connection handlers, see Chapter 25, Connections Between Clients and Directory Proxy Server .

Add an ACI That Allows Anonymous Access

Add the ACI.

$ ldapadd -v -D "cn=proxy manager" -w password -p 389
dn: cn=ldifonly-acis,cn=virtual access controls
objectclass: top
objectclass: aciSource
cn: ldifonly-acis
dpsaci: (targetattr="*")(version 3.0; acl "anonymous_access"; allow(all) \
(userdn="ldap:///anyone");)

Point the connection handler to the virtual ACI.

$ dpconf set-connection-handler-prop anonymous aci-source:ldifonly-acis

Enable the connection handler.

$ dpconf set-connection-handler-prop anonymous is-enabled:true

Chapter 22 Directory Proxy Server Virtualization

Creating and Configuring LDIF Data Views

To Create an LDIF Data View

To Configure an LDIF Data View

Defining Access Control on Virtual Data Views

To Define a New ACI Storage Repository

To Configure Virtual Access Controls

Defining Schema Checking on Virtual Data Views

To Define Schema Checking

Creating and Configuring Join Data Views

To Create a Join Data View

To Configure a Join Data View

To Configure a Join Data View to Enable Referencing of a Data View by Multiple Join Data Views

To Configure the Secondary View of a Join View

Creating and Configuring Coordinator Data Views

To Create a Coordinator Data View

To Configure a Coordinator Data View

Creating and Configuring JDBC Data Views

To Create a JDBC Data View

To Configure a JDBC Data View

To Configure JDBC Tables, Attributes, and Object Classes

Defining Relationships Between JDBC Tables

Example 22–1 is-single-row-table:true and contains-shared-entries:true

Example 22–2 is-single-row-table:true and contains-shared-entries:false

Example 22–3 is-single-row-table:false and contains-shared-entries:false

Example 22–4 is-single-row-table:false and contains-shared-entries:true

Sample Virtual Configurations

Joining an LDAP Directory and a MySQL Database

Figure 22–1 Sample Virtual Configuration

Configuring and Testing the LDAP Data View

To Configure the LDAP Data View

Before You Begin

To Test the LDAP Data View

Configuring and Testing the JDBC Data View

To Configure the JDBC Data View

To Create the Required ACIs

To Test the JDBC Data View

Creating and Testing the Join Data View

To Create the Join Data View

To Create the Required ACIs

To Test the Join Data View

Joining Multiple Disparate Data Sources

Data Storage Scenario

Figure 22–2 Data Storage In Disparate Sources

Client Application Requirements

Figure 22–3 Client Application Requirements

Aggregate Data From the HR LDAP Directory and the Administration LDIF File

Figure 22–4 Aggregation of Data From LDAP Directory and LDIF File

Create and Enable an LDAP Data View for the Payroll Directory

Create and Enable an LDIF Data View for the Administration Data

Join the Payroll Data View and the Administrator Data View

Add Data From Company 22 to Example.Com's DIT by Renaming the DN

Figure 22–5 DN Renaming

Create a Data View For Company 22's Directory With a Virtual DN

Add Company 22's Data to the HR Data

Figure 22–6 Aggregation of Data From Join Data View and LDAP Data View

Join the Example Join Data View and the Company 22 Data View

Enable LDAP Clients to Access the Payroll Data in an SQL Database

Figure 22–7 JDBC Dataview Providing Access to an SQL Database

Create a JDBC Data View For Example.com's Payroll Database

Add Virtual Access Control

Add an ACI That Allows Anonymous Access

Example 22–1 `is-single-row-table:true` and `contains-shared-entries:true`

Example 22–2 `is-single-row-table:true` and `contains-shared-entries:false`

Example 22–3 `is-single-row-table:false` and `contains-shared-entries:false`

Example 22–4 `is-single-row-table:false` and `contains-shared-entries:true`