Sun Directory Server Enterprise Edition 7.0 Reference

Chapter 18 Directory Proxy Server Virtualization

Directory Proxy Server enables virtualization through the definition of virtual data views. Virtual data views enable you to display physical data in a different way. This chapter describes how virtual data views are created, and the kinds of virtual data views that are available in Directory Proxy Server.

The chapter covers the following topics:

Construction of Virtual Data Views

A virtual data view is essentially a physical data view on which certain transformation actions have been defined. The transformation actions take place in real time, to create the virtual data view. The following figure shows how transformation actions are defined on a physical data view to create a virtual data view.

Figure 18–1 Virtual Data View

Figure shows transformation of a physical data view to
a virtual data view.

In addition to the transformation actions, certain properties can be defined on a data view, which restrict the way in which data can be managed through that data view. The additional virtual data view properties are described in Additional Virtual Data View Properties.


Caution – Caution –

Virtual data views imply a performance impact. The significance of the performance impact depends on several factors including the size of the physical data source, the complexity of the transformation, and the complexity of any virtual ACIs you might use.


Virtual Data Transformations

Virtual data transformations create a virtual data view from a physical data view. Practically, you never define a virtual data view. Instead, you specify the transformations that you require and define these on an existing physical data view. A transformation performs a specific action in a certain direction. The direction of a transformation determines the transformation model. When you define a virtual data transformation, you create a virtual attribute that exists only in the context of the virtual data view.

A transformation is defined on a data view, by using the dpconf command as follows:

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
 view-name model action attr-name [parameters...]

The view-name refers to the data view on which the transformation is defined. The attr-name refers to the virtual attribute that is created. The model, action, and additional parameters are described in the following sections.

The name of the virtual transformation can be set by using the following command:

$ dpconf set-virtual-transformation-prop -h host -p port -D bindDN /
 view-name transformation-name property:value [property:value]

Transformation Models

The transformation model is determined by the direction of a transformation, in other words, whether the transformation is applied during the request, during the response, or both.

In this sense, transformations can be categorized into the following types:

Mapping Transformations

The most common transformation is a bidirectional (mapping) transformation. A mapping transformation is applied during the request, and its inverse is applied during the response. These transformations are called mappings because in effect, an attribute or entry in the physical data view maps to an attribute or entry in the virtual data view. Mapping transformations enable you to process existing values before assigning them to a DN component, an attribute type or value, or an object class.

The following diagram illustrates the principals of a mapping transformation.

Figure 18–2 Mapping Transformation

Figure shows a high level view of how a mapping transformation
works

A mapping transformation is defined on a data view, by running the dpconf command as follows:

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name mapping action attr-name [parameters]

Example 18–1 When Would You Use a Mapping Transformation?

Imagine, for example, an organization has a physical data source that contains entries with the attributes surname and givename. The organization has a client application that requires entries to have a cn (common name) attribute of the form givenname surname.

The client application sends a search request for an entry of the form cn=Carlos Fuentes. A transformation is defined that extracts the name and surname during this request and transforms the request to one of the form surname=Fuentes, givenname=Carlos. The corresponding entry is located in the data source. Before returning this entry to the client application, the inverse transformation is performed. The client application receives the entry as cn=Carlos Fuentes, which it understands.

This request is transformed to be of the form surname=Fuentes, givenname=Carlos. Similarly, the client application sends a modify request to change the cn attribute of an entry to Lisa Davis. The request is transformed so that the givenname attribute of the physical entry is modified to Lisa and the surname attribute is modified to Davis.


Write Transformations

A write transformation is applied during the request, but not during the response. A write transformation changes the physical data in storage.

The following diagram illustrates the principals of a write transformation.

Figure 18–3 Write Transformation

Figure shows a high level view of how a write transformation
works

A write transformation is defined on a data view, by using the dpconf command as follows:

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name write action attr-name [parameters]

Example 18–2 When Would You Use a Write Transformation

Imagine an organization has a legacy application whose function is to add person entries to a data source. The application adds the entries without the telephoneNumber attribute. The physical data source has been upgraded and the telephoneNumber is now a mandatory attribute for person entries. The transformation required here is to add the telephoneNumber attribute during the add request. This transformation changes the entry that is written to the database. No reverse transformation is required.


Read Transformations

A read transformation is applied only during the response to a request. No transformation is applied during the request and the physical data is not changed.

The following diagram illustrates the principals of a read transformation.

Figure 18–4 Read Transformation

Figure shows a high level view of how a read transformation
works

A read transformation is defined on a data view, by using the dpconf command as follows:

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name read action attr-name parameters

Example 18–3 When Would You Use a Read Transformation

Imagine an organization has a legacy application whose function is to display person entries. The application does not support entries that do not contain a mail attribute. The physical data source has been upgraded and the email attribute no longer exists for person entries (e-mail addresses are constructed using other attributes).

The transformation required here is to add the mail attribute during the search response. This transformation changes the entry that is read from the database and adds a mail attribute whose value is givenname.surname@example.com. No reverse transformation is required and the physical data is not changed.

Note that with the above transformation, the mail attribute makes no sense in a search request filter. Search request filters must contain physical attributes.


Transformation Actions

Transformation actions describe what a transformation does to its target entry or entries. The following transformation actions are possible:

The results of a transformation action depend on the transformation model.

Transformation Parameters

Transformation parameters provide the value of a virtual attribute. This value can either be a default value, or rule that creates the value from other attribute values.

The following transformation parameters are accepted:

Transformation parameters take the following syntaxes:


Note –

The transformation parameter syntax is slightly different when used in the context of a join data view. For more information, see Virtual Data Transformations on Join Data Views.


Transformation Examples

The following sections provide use cases in which virtual data views are required, and the combination of transformation models and actions required to implement the use cases.


Example 18–4 Adapting an ADAM Object Class For LDAP Compliance

An organization, Example A, stores its users in an LDAP directory. Example A acquires another company, Example B, which stores its users in an ADAM directory.

In Example A's LDAP directory, a user is stored as an inetOrgPerson. In Example B's directory, a user is stored as a user. A transformation is required that maps the ADAM user object class to the LDAP inetOrgPerson object class.

The following transformation is defined on the physical data view of Example A's directory:

$ dpconf add-virtual-transformation -h myHost -p 2389 -D "cn=Proxy Manager" \
 exampleB-view-name mapping attr-value-mapping objectclass internal-value:user \
 view-value:inetOrgPerson


Example 18–5 Constructing an Attribute With a Write Transformation

Example A stores user entries in its directory. All user entries require a mail attribute. If user entries without a mail attribute are added, a schema violation error is returned. Example A has a client application that adds user entries to the directory. Some user entries do not contain a mail attribute and the client application is incapable of generating one. To avoid schema violations when a user entry is added, a transformation is defined that adds the mail attribute to an add request. The value of the mail attribute is taken from the uid provided in the client add request, with the addition of @example.com.

The following diagram indicates the transformation that occurs on an add request.

Figure shows the creation of an attribute with a write
transformation

This transformation is defined on the physical data view by using the following dpconf command.

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name write add-attr mail \${uid}@example.com

In this command, \${uid} means the value of the uid attribute for that entry.



Example 18–6 Constructing an Attribute With a Read Transformation

Example A does not store the mail addresses of its users in its directory. However, a new client application requires that a user's mail address be returned with the user entry.

All mail addresses in the organization take the form firstname.lastname@example.com. The organization defines a virtual view in which the mail attribute is added to each user entry for reads only. The value of the mail attribute is generated by taking the value of the givenName and sn attributes that already exist in the user entry.

The following diagram indicates the transformation that occurs on user entries when they are returned in a search.

Figure shows the creation of an attribute with a read
transformation

This transformation is defined on the physical data view by using the following dpconf command.

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read add-attr mail \${givenname}.\${sn}@example.com


Example 18–7 Adding a Default Attribute Value

Example A stores a number of products in its directory. In the past, each product was associated with a support person, an employee responsible for handling all support calls for that product. In the physical data store, each product is therefore associated with a supportPerson attribute, whose value is the DN of an employee in the organization.

The organization has changed its business process for support queries and now sends all product queries to a central hotline. To handle this change without changing the physical data, the organization defines a virtual data view where all product entries do not have a supportPerson attribute, but have a hotline attribute instead. The value of the hotline attribute is an 0800 number that is the same for all products.

The following diagram indicates the transformation that occurs on product entries when they are returned in a search.

Figure shows transformation of an entry with no reference
to other entries.

This transformation is defined on the physical data view by using the following dpconf commands:

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read remove-attr supportPerson
$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read add-attr hotline "0800755 8625"


Example 18–8 Using a Virtual Transformation to Rename a DN

Example A has a client application that needs to sort entries according to their object class.

To do this, Example A defines a virtual transformation that rewrites the RDN of entries to include the object class of the entry along with its cn, whenever an entry is returned to that specific client application.

The following transformation is defined on the physical data view of Example A's directory:


$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleB-view-name mapping attr-value-mapping dn internal-value:cn=\${cn} \
 view-value:cn=\${cn},objectclass=\${objectclass}

Additional Virtual Data View Properties

In addition to the transformation actions described previously, certain properties can be defined on a data view, which restrict the way in which data can be managed through that data view. These properties essentially provide a list of the attributes that can be read or modified through the virtual data view.

The following additional properties can be defined on a data view to present a restricted virtual data view:

Non-viewable attributes and viewable attributes are mutually exclusive. Similarly, non-writable attributes and writable attributes are mutually exclusive.

Join Data Views

A join data view is an aggregation of multiple data views. The current release of Directory Proxy Server supports the aggregation of two data views into one join data view.

A join data view is created by specifying its name and the two existing data views that will be aggregated. One of these existing data views is considered the primary data view, and the other the secondary data view. Before you create the join data view, you need to configure the rules on the secondary data view that determine how the data is aggregated.

The following figure shows the aggregation of a primary and secondary data view to form one join data view.

Figure shows aggregation of two join source data views.

Primary and Secondary Data Views

The hierarchical organization of the sources for a join data view enables Directory Proxy Server to make default decisions where the data from the primary and secondary data views do not match.

The primary data view controls the existence of entries in the join data view. The secondary data view provides supplementary data for this list of entries. In other words, if an entry exists in the secondary data view but not in the primary data view, it does not appear in the join data view.

The primary data view is the authoritative source by default. When an attribute is present on both source data views but has a different value on each, a multi-valued attribute is returned. This behavior is configurable, however. For example, you can choose to accept only the value in the primary data view, or only the value in the secondary data view.

Additional Secondary Data View Properties

In addition to the virtual data view properties described in Additional Virtual Data View Properties, certain properties can be defined only on a secondary data view. These properties determine how data from the two views is aggregated and how requests to the data views are handled. The following sections describe these additional properties.

Join Rules

Join rules determine how an entry from a secondary data view relates to an entry from a primary data view. Join rules are not mandatory on a secondary data view. However, if no join rule is defined, the secondary data view is not queried during LDAP operations. Directory Proxy Server provides two types of join rules, DN join rules and filter join rules.

DN Join Rules

A DN join rule determines the DN of entries in the secondary data view. A DN join rule is configured on the secondary data view by using the dn-join-rule property. Only one DN join rule can be configured on a secondary data view. If a DN join rule is configured on a data view, a filter join rule cannot be configured on that data view.

A DN join rule has DN syntax and can take one of the following forms:

Filter Join Rules

A filter join rule defines the relationship between the primary and secondary data views. A filter join rule is configured on the secondary data view by using the filter-join-rule property. This rule indicates how an entry should be retrieved from the secondary data view based on something in the primary data view.

Only one filter join rule can be configured on a secondary data view. If a filter join rule is configured on a data view, a DN join rule cannot be configured on that data view. A filter join rule takes the form of a filter that is used to construct an attribute from one or more attributes from the primary data view.

For example, the following filter join rule stipulates that an entry be retrieved if the entry uid in the primary data view matches the entry uid in the secondary data view.

uid=\${primary.uid}

Handling of Shared Entries

The contains-shared-entries property determines what should be done if an entry in the secondary data view is used by more than one entry in the primary data view.

Imagine for example, that the primary data view contains a list of user entries and the secondary data view contains a list of department numbers. A single department number in the secondary data view might apply to more than one user in the primary data view. If a user is deleted from the primary data view, you do not necessarily want that user's department number to be deleted from the secondary data view.

The contains-shared-entries property is set on the secondary data view only. This property is set to TRUE by default. This means that deleting an entry in the primary data view will not result in the deletion of the shared entry in the secondary data view. Adding an entry to the primary data view will only add the entry to the secondary data view if it does not already exist.

Handling of Binds

The process-bind property specifies whether a bind can be performed on the secondary data view.

By default, primary data views allow binds and secondary data views do not. The process-bind property is not set by default. If this property is set to true on a secondary data view, binds are permitted on that data view.

How Directory Proxy Server Handles Read and Write Operations to Join Data Views

If an attribute exists on both the primary and secondary data view, the attribute values are merged by the join data view. For read operations, this implies that a multi-valued attribute is returned, with the values from both data views. For write operations, the proxy queries both data views and determines where to write the value based on the content of the write operation.

If one backend data source fails during an add operation Directory Proxy Server performs an automatic rollback. The roll back takes the form of a delete operation on the data source that did not fail. This ensures the consistency of the data between the two data sources. If a roll back cannot be performed, an error is logged and an optional administrative alert is raised. Automatic roll back is on by default. You can configure automatic roll back by setting the revertAddOnFailure attribute to off (directly in cn=config).

If one backend data source fails during a delete operation, no roll back is performed. An error is logged and an optional administrative alert is raised.

Virtual Data Transformations on Join Data Views

Virtual data transformations are described in Virtual Data Transformations. The syntax of a transformation parameter differs slightly if the data transformation is defined on a join data view. Because an attribute can be obtained from more than one data view, variables that define the attribute content must be fully qualified. That is, the source attribute value must include the name of the data view from which the attribute is taken.

For example, the following parameter creates an attribute from existing attributes in both the primary and secondary data views:

\${primaryDataView.firstName}.\${secondaryDataView.lastName}@\${primaryDataView.domainName}

The firstName and domainName attributes are taken from the primary data view, and the lastName attribute is taken from the secondary data view.

Coordinator Data Views

Coordinator Data View groups a sequence of data views so that they appear as a single data view. This grouping enables users to access entries that are stored in separate data views, without knowing where each entry is stored while performing operations. The data view automatically discovers where each entry is stored and performs operations on them.

Features of Coordinator Data View

For all the configuration details, see Creating and Configuring Coordinator Data Views in Sun Directory Server Enterprise Edition 7.0 Administration Guide

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. An LDIF data view is defined by using the dpconf command as follows:

dpconf create-ldif-data-view VIEW_NAME LDIF_FILE_NAME SUFFIX_DN

No additional transformations are required. Directory Proxy Server automatically performs the transformations required to make the LDIF data look like LDAP data to client applications.

For information about creating and configuring LDIF data views, see Creating and Configuring LDIF Data Views in Sun Directory Server Enterprise Edition 7.0 Administration Guide.

JDBC Data Views

A JDBC data view enables you to make a relational database accessible to LDAP client applications. The following configuration objects are required to set up a JDBC data view:

The following diagram shows how an LDAP client application is able to view an Oracle database in the format of an LDAP DIT, through the configuration of the JDBC objects described previously. These objects are discussed in more detail in the following sections.

Figure shows RDBMS accessible to LDAP client applications.

An LDAP client application can also bind to a JDBC data view, or to a join data view that includes a JDBC data view. In this case Directory Proxy Server obtains the password from the JDBC database to do the password check. The password can be obtained in clear, SHA, or SSHA.

JDBC Data Sources and Data Source Pools

A JDBC data source is defined for each relational database. The properties of a JDBC data source include the name and location of the relational database, and the user name and password required to access the database. For a complete list of the properties that can be set for a JDBC data source, run the following command:


$ dpconf get-jdbc-data-source-prop -h myHost -p 2389 -d "cn=Proxy Manager"\
 jdbc-data-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.

Like LDAP data sources, JDBC data sources are organized into data source pools. The properties of a JDBC data source pool are similar to those of an LDAP data source pool. For more information about LDAP data source pools see LDAP Data Source Pools.


Note –

Directory Proxy Server relies on metadata retrieved from the relational database. This metadata is read when Directory Proxy Server starts, or when a new JDBC data view is added. The metadata is not reread each time Directory Proxy Server processes a request. If you change the metadata in the relational database, you must restart Directory Proxy Server to take the changes into account.

The metadata is changed when any of the following changes are made:


JDBC Object Classes

A JDBC object class maps an LDAP object class to one or more relational database tables. A JDBC object class works in a similar way to a join data view (see Join Data Views). Just as a join data view has primary and secondary source data views, a JDBC object class can obtain its information from more than one table. One table must be defined as the primary table, and additional tables, if they exist, are defined as secondary tables. The primary table controls the list of entries and additional information on these entries is extracted from the secondary tables.

When you define a JDBC object class, you must specify the following operands:

JDBC Tables

A JDBC table must be created for each relational database table that will be used in the JDBC data view. When you create a JDBC table you specify the name of the table in the relational database, and the name you want to assign to this table in the JDBC data view.

The following properties apply to JDBC tables:

JDBC Attributes

JDBC attributes map LDAP attributes to entries in relational database tables. The definition of a JDBC attribute includes the name of the LDAP attribute, and the table and column in which the corresponding information is located.

For example, the following command maps the employeeNumber attribute to the ID field of the EMPLOYEE table.

$ dpconf add-jdbc-attr -h myHost -p 2389 -d "cn=Proxy Manager" \
 EMPLOYEE employeeNumber ID

The following properties apply to JDBC attributes:

Case Sensitivity in JDBC Data Views

In some cases, the LDAP attribute might be case insensitive, while the corresponding column in the relational database is case sensitive. Directory Proxy Server handles this by adding an UPPER keyword to equality and substring indexes. This can have serious performance implications. If the relational database requires case-sensitivity, you should therefore create specific indexes on the upper case values.

Access Control On Virtual Data Views

In a virtual data view, Directory Proxy Server exposes virtual data. Directory Proxy Server is therefore responsible for controlling who can access that data, and what parts of the data can be accessed. To control access to virtual data, you can define virtual ACIs. When Directory Proxy Server receives a request on a virtual data view, it uses the virtual ACIs, and any authentication information provided by the user, to allow or deny access to the information that is requested.

This section describes the syntax and architecture of virtual ACIs. For information about configuring virtual ACIs, see Defining Access Control on Virtual Data Views in Sun Directory Server Enterprise Edition 7.0 Administration Guide.

Virtual ACI Definition

Virtual ACIs are defined by using the dpsaci operational attribute. The dpsaci attribute is multi-valued. This means that several ACIs can be defined for the same portion of a directory.

Directory Proxy Server is responsible for the management of the dpsaci attribute. This attribute can be configured along with the physical data but it is not stored with the data. When the dpsaci attribute is included in a request, Directory Proxy Server extracts it from the request and manages it in a dedicated ACI repository, through its own ACI data view.

A modify request that targets a virtual data view and contains the dpsaci attribute is effectively split into two requests by Directory Proxy Server. The first request handles only the virtual data, and the second request handles the virtual ACI.


Note –

By default, write operations are forbidden on non-LDAP data views.


Global ACIs

Global ACIs are defined in the entry cn=data-source-name,cn=virtual access controls. These ACIs are evaluated by an ACI engine to deny or allow requests from a connection handler using that ACI pool. Global ACIs are required to allow or deny application administrators to access certain data. These application administrators can then provide more finely-grained access control to users, by placing ACIs directly in the data.

Only the proxy manager can create a pool of ACIs and manage ACIs directly through the ACI data view. Application administrators cannot manage ACIs directly through the ACI data view, even if they have the right to add entries. Application managers can only manage ACIs directly through the data.

ACIs that are defined in the data itself, are evaluated by Directory Proxy Server. These ACIs are entries in the pool of ACIs defined by the proxy manager, that is they are child entries of the entry cn=data-source-name,cn=virtual access controls.

ACIs have a performance impact. Therefore, if you use ACIs within the data itself, keep to a minimum the number of rules in the global ACIs, because these ACIs are evaluated every time the subtree is accessed.

Virtual ACI Syntax

The dpsaci attribute resembles the Directory Server aci attribute in syntax and behavior. For a description of Directory Server ACI syntax, see How Directory Server Provides Access Control.

The following list describes the differences between virtual ACIs and Directory Server ACIs.

Virtual ACI Storage and Access

Virtual ACIs are stored centrally, in an LDIF file or in an LDAP directory. When you create a Directory Proxy Server instance, the virtual ACIs are stored in the LDIF file instance-path /config/access_controls.ldif by default. You can change the location of the virtual ACIs, particularly if you need to share ACIs across multiple proxy servers. For information about how to change the location of virtual ACIs, see To Define a New ACI Storage Repository in Sun Directory Server Enterprise Edition 7.0 Administration Guide.

The ACI repository is accessed through an LDAP or LDIF data view, depending on the type of repository. By default, the access control data view is an LDIF data view named virtual access controls. The view base exposed by the access control data view must exist in the ACI repository.

The ACI repository contains one or more pools of ACIs. An ACI pool is defined by an LDAP entry of the type aciSource, directly below the view base of the data view. The ACI pool is a subtree of entries. It can contain access controls, and can be the parent entry of other entries containing ACIs.

Virtual ACI Application

Virtual ACIs are applied per connection handler. The name of the ACI pool to be used is defined as the aci-source property of the connection handler. Virtual access controls are not evaluated if you bind as the Proxy Manager.

Virtual Schema Checking

Directory Proxy Server exposes its own schema that is different to the schema of a physical data source. The Directory Proxy Server schema can be stored locally in an LDIF file, or in a remote Directory Server. You can configure where the schema is stored with the dpconf command. A schema is defined per connection handler. The schema for a specific connection handler can be retrieved or updated using ldapsearch or ldapmodify. When the schema is updated, Directory Proxy Server must be restarted before the changes take effect.

Schema Checking

Generally, schema checking is performed by the server that exposes the schema. In a scenario where Directory Proxy Server acts as a proxy to one or more Directory Servers, the Directory Servers check that add and modify requests adhere to their LDAP schema. When Directory Proxy Server exposes its own schema. Directory Proxy Server must check that add and modify requests adhere to these schema.

Because a schema is defined for a specific connection handler, schema checking is enabled per connection handler. Schema checking is enabled by setting the schemaCheck attribute of a connection handler to true.

Virtual Data Views and LDAP Groups

With virtual data views, you can define local virtual groups, and use them though ACIs. You can also rely on existing groups defined on backend servers. You can transform the groups from an LDAP directory to appear in the virtual namespace by using DN mapping. You can also transform all member DNs by using attribute value renaming.

With a join data view, you can join two static groups from two different LDAP backends, as long as there are no member naming conflicts. You can also create a read-only virtual group, by using an ACI on the uniquemember attribute, for example.

Directory Proxy Server server uses groups in the area of ACIs only. The ACI engine can reference both static and dynamic groups by using the groupdn keyword.

Virtual ACIs support both static and dynamic groups. However, the isMemberOf feature is not supported. Due to the severe performance impact, nested groups are also not supported.

With dynamic groups, attribute value renaming does not apply to the value of the dynamic group, because this value is an LDAP URL and is therefore not DN syntax. In other words, if a dynamic group value contains a DN, the DN part is not renamed.