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 JDBCTM 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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
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:
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.
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).
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 : "" alternate-search-base-dn : dc=com attr-name-mappings : none base-dn : suffixDN bind-pwd-attr : userPassword contains-shared-entries : - db-pwd-encryption : clear-text 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 ldif-data-source : /path/to/filename.ldif 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-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 |
Virtual data transformations are defined on existing data views, and create a virtual data view from a physical data view. For information about how they work, see Virtual Data Transformations in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You can add a virtual data transformation to any type of data view: an LDAP data view, an LDIF data view, a join data view, or a JDBC data view.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Add the transformation to a data view.
$ dpconf add-virtual-transformation -h host -p port view-name \ transformation-model transformation-action attribute-name [parameters...] |
Note that parameters might be mandatory, depending on the transformation-model and the transformation-action. For information about transformation models, transformation actions, and transformation parameters, see Virtual Data Transformations in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
(Optional) View the list of virtual transformations that are defined on a data view.
$ dpconf list-virtual-transformations -h host -p port view-name
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
For information about how to create and configure join data views, see the following procedures.
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 |
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:
alternate-search-base-dn : "" alternate-search-base-dn : dc=com attr-name-mappings : none base-dn : suffixDN 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 join-rule-control-enabled : false 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 primary-view : primary-view process-bind : - replication-role : master secondary-view : secondary-view 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-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 |
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.
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} |
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
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.
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} |
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
(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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
For information about how to create and configure JDBC data views, see the following procedures.
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:
The name of the relational database, for example, payrolldb.
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.
The JDBC driver class, for example org.hsqldb.jdbcDriver.
The path to the JDBC driver, for example file:///path/to/hsqldb/lib/hsqldb.jar.
The driver-url property is multi-valued. Hence, driver-url can support multiple JAR files for the JDBC driver to ensure connectivity to the JDBC source on different platforms.
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 |
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-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 ... ] |
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.
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. The DN pattern shows how the DN of the entry will be constructed.
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.
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.
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}" |
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.
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}" |
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.
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}" |
This case is currently unsupported in Directory Proxy Server.
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference.
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.
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 and an LDAP data view, as described in Creating and Configuring 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
Regardless of the ACI repository that you use, you must configure the virtual access controls.
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference. 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=data-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: data-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:data-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";) |
Any user with the appropriate access rights can add and retrieve virtual ACIs through the data view.
Generally, for LDAP data views, schema checking is performed by the backend directory, using the backend 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:
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 Creating and Configuring 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 a 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 |
The following section provides two sample configurations. These configurations illustrate the main features of a virtual directory, and indicate how these features are configured.
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.
You can use the sample data provided in install-path/ds6/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:
1389
pwd.txt, a file containing the administrator password.
4389
cn=Directory Manager
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/ds6/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 |
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=*" |
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 |
A default ACI in Directory Server allows users to modify their own passwords.
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, TITLE, COUNTRY_ID |
COUNTRY |
ID, NAME |
PHONE |
USER_ID, NUMBER |
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 |
Specify the user name and password file for the SQL database.
% dpconf set-jdbc-data-source-prop mysql1 db-pwd-file:sqlpwd.txt db-user:root |
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 |
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 room ROOM % dpconf add-jdbc-attr phone1 tel NUMBER % dpconf add-jdbc-attr country1 country NAME |
It is not necessary to create JDBC attributes for the phone1 user_id and country1 id columns, because these columns are used only in the context of the MySQL database. They will not have a corresponding LDAP attribute.
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 |
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 |
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=*" |
You must use the credentials of a user under o=sql, or an anonymous bind.
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 |
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} |
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:room viewable-attr:userpassword viewable-attr:jobtitle \ viewable-attr:country viewable-attr:tel % dpconf set-jdbc-data-view-prop mysql1-view writable-attr:dn writable-attr:objectclass \ writable-attr:sn writable-attr:room writable-attr:userpassword writable-attr:jobtitle \ writable-attr:country writable-attr:tel |
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.
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 |
Create a connection handler to handle connections to the o=join domain.
% dpconf create-connection-handler myjoin1-handler |
Enable the connection handler and configure it to handle all binds from users under o=join.
% dpconf set-connection-handler-prop myjoin1-handler is-enabled:true \ bind-dn-filters:"uid=.*,ou=people,o=join" |
Configure the connection handler to use the pool of ACIs added previously.
% dpconf set-connection-handler-prop myjoin1-handler aci-source:myjoin1 |
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 -D "uid=kvaughan,ou=people,o=join" -w myNewPassword dn: uid=kvaughan,ou=people,o=join changetype: modify replace: userPassword userPassword: myPassword |
This configuration describes an organization, Example.com, whose specific directory service requirements are met by some of the features of a virtual directory.
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.
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.
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 Sun Java System Directory Server Enterprise Edition 6.2 Reference and Chapter 18, Directory Proxy Server Virtualization, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The configuration of the sample scenario is divided into the following sections:
Aggregate Data From the HR LDAP Directory and the Administration LDIF File
Add Data From Company 22 to Example.Com's DIT by Renaming the DN
Enable LDAP Clients to Access the Payroll Data in an SQL Database
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.
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. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
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: dpcfg create-ldap-data-view VIEW_NAME POOL_NAME SUFFIX_DN
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 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 admin 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 admin 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
Create a filter join rule on the admin 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
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.
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. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
The Company 22 LDAP directory runs on a host named company22Host, on port 2389.
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 -h company22Host -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
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.
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
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.
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. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
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 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.
$ dpcfg 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.
$ set-jdbc-object-class-prop payroll-view person super-class:extensibleObject
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 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