Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Unified Directory
11g Release 2 (11.1.2)

Part Number E22648-05
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

11 Understanding the Proxy Functionality

This chapter describes the functionality that is specific to a proxy server instance, and covers the following topics:

Note:

Before you read this chapter, review Chapter 1, "Overview of Oracle Unified Directory" for a better understanding of the concepts described here.

11.1 Load Balancing Using the Proxy

You can use the proxy to load balance requests across multiple data sources or replicated LDAP servers.

In a load balancing deployment, the requests are routed to one of the data sources based on the load balancing algorithm set.

You can choose one of the following load balancing algorithms:

11.1.1 Failover Load Balancing

In a load balancing with failover algorithm, the proxy routes requests to the remote LDAP server or data center with the highest priority for a given operation type, for example for Add operations. The proxy continues to send requests to the priority route until the remote LDAP server goes down. This may be caused by a network cut, a hardware failure, a software failure or some other problem. At failover, the proxy routes incoming requests to the server with the second highest priority for that specific operation type.

Figure 11-1 illustrates a failover load balancing configuration. In this example, there are three routes, each with a unique priority per operation type. All Add operations are treated by Server 1, since it has the highest priority, that is priority=1, while Bind operations are handled by Server 2. If Server 1 goes down, the Add requests are sent to the server with the second highest priority, that is, Server 2.

Figure 11-1 Failover Load Balancing Example

Description of Figure 11-1 follows
Description of "Figure 11-1 Failover Load Balancing Example"

By default, the proxy does not immediately reroute requests to a server that has gone down, once it is running again. For example, if Server 1 goes down, the Add requests are sent to Server 2. Even when Server 1 is up again, Server 2 continues to handle incoming Add requests. However, if Server 2 goes down, and Server 1 is up again, Server 1 will now receive incoming requests. This default behavior can be changed with the switch-back flag. For information about configuring the switch-back flag, see Section 15.1.3.5.2, "Setting the switch-back Flag."

For failover to work effectively, the monitoring check interval must be set to be low enough so that the failover happens inside a time interval that suits your business needs. For details about setting the monitoring check interval, see Chapter 29, "Monitoring Oracle Unified Directory."

11.1.2 Optimal Load Balancing

With the optimal load balancing algorithm, the proxy sends requests to the route with the lowest saturation level. The proxy continues to send requests to this route until the saturation level of the remote LDAP server on that route passes the saturation level of the other remote LDAP servers in the deployment. The saturation level is represented as a percentage.

When the saturation level of a route changes, the load balancing algorithm re-evaluates the best route and if required, selects another route as the active one. The route with the lowest saturation level is always chosen as the optimal route. In the configuration illustrated by Figure 11-5, Server 1 has the lowest saturation level and will handle all the requests until its saturation level rises above the saturation level of the other servers. If one of the servers goes down, its saturation level is considered as 100%.

Figure 11-2 Optimal Load Balancing Example

Description of Figure 11-2 follows
Description of "Figure 11-2 Optimal Load Balancing Example"

You can configure the saturation precision, to set the difference of saturation between two servers before the route changes to the server with the lowest saturation level. By default, the saturation precision is set to 5. However, if you find that the algorithm is switching between servers too often, you can set the saturation precision to 10, for example. The saturation precision is set in the LDAP server extension, see Section 15.1.3.5.3, "Setting the Saturation Precision for the Optimal or Saturation Algorithm."

11.1.2.1 Determining Saturation Level

The saturation level is a ratio between the number of connections in use in the connection pool and its configured maximum size. The connection pool maximum size is an advanced parameter of the LDAP server extension object.

If the number of connections in use is lower than the maximum pool size divided by 2, then the saturation is 0. This implies that the pool is not saturated.

When more than half of the connections are in use, the saturation level is calculated as follows:

100 * (1 - available connections/(max pool size/2))

This implies that the saturation level is 100 when all the connections are in use.

11.1.3 Proportional Load Balancing

With the proportional load balancing algorithm, the proxy forwards requests across multiple routes to remote LDAP servers or data sources, based on the proportions set. The proportion of requests handled by a route is identified by the weight that you set for each route in your configuration. The weight is represented as an integer value.

When you configure load balancing, you must indicate the proportion of requests handled by each LDAP server. In the example in Figure 11-3, Server 1 handles twice as many connections as Server 2, since the weight is set with a proportion of 2:1. Server 2 and Server 3 handle the same amount of requests (1:1).

Figure 11-3 Proportional Load Balancing Example

Description of Figure 11-3 follows
Description of "Figure 11-3 Proportional Load Balancing Example"

You can configure a specific weight for each type of client operation, as illustrated in Figure 11-4. For example, in you want Server 1 to handle all the Bind operations, this is possible. To do so, set the weight of bind to 1 (or higher) for Server 1, and to 0 for Server 2 and Server 3.

In the example illustrated in Figure 11-4, Server 1 will handle three times as many Add requests as Server 2 and Server 3. However, Server 1 will handle only one half the Search requests handled by Server 2, and Server 3. Server 2 and Server 3 will handle the same amount of Add and Search requests, but will not handle Bind requests.

Figure 11-4 Proportional Load Balancing with Request Specific Management

Description of Figure 11-4 follows
Description of "Figure 11-4 Proportional Load Balancing with Request Specific Management"

If you do not modify the weights of operations other than Bind, Add, and Search, as illustrated in Figure 11-4, the servers will share the same load for all other operations (for example for Delete operations).

For more information on configuring the load balancing weights of routes when using proportional load balancing, see Section 15.1.3.5, "Modifying Load Balancing Properties."

11.1.4 Saturation Load Balancing

With the saturation load balancing algorithm, the proxy sends requests to a chosen priority route. The proxy continues to send requests to the priority route until the remote LDAP server on that route passes the saturation threshold set. The saturation threshold is represented as a percentage.

For example, if you want a remote LDAP server to manage all incoming requests, set it as priority 1. If you want that same remote LDAP server to stop handling requests when its saturation index reaches 70%, set the saturation threshold to 70%, as illustrated in Figure 11-5. In this way, the server handles all incoming requests until it becomes 70% saturated. The proxy then sends all new requests to the remote LDAP server to Server 2, since it has the next highest priority. Server 2 will continue to handle requests until it reaches its own saturation threshold, or until Server 1 is no longer saturated.

In other words, if Server 1 reaches 70% saturation, the proxy directs the requests to Server 2. If Server 1 is still at 70%, and Server 2 reaches 60%, the proxy directs the new requests to Server 3.

However, if while Server 2 is handling requests, the saturation level of Server 1 drops to 55%, the proxy will direct all new requests to Server 1, even if Server 2 has not reached its saturation threshold.

Figure 11-5 Saturation Load Balancing Example

Description of Figure 11-5 follows
Description of "Figure 11-5 Saturation Load Balancing Example"

If all routes have reached their saturation threshold, the proxy chooses the route with the lowest saturation.

You can set a saturation threshold alert that warns you when a server reaches its saturation limit. For example, if you set a saturation threshold alert to 60%, you will receive a notification when the server reaches this limit, and you can act before the server becomes too degraded.

For more information about how to determine the saturation level, see Section 11.1.2.1, "Determining Saturation Level."

11.1.5 Search Filter Load Balancing

With the search filter load balancing algorithm, the proxy routes search requests to LDAP servers based on the presence of certain attributes defined in the request search filter.

The topology consists of several LDAP servers that are accessible through the proxy. All the LDAP servers contain similar data, but each server is optimized based on attributes defined in the search filter to provide better performance. You can configure each route with a list of allowed attributes and a list of prohibited attributes. A search request matches a route when the request search filter contains at least one allowed attribute, and none of the prohibited attributes.

The Figure 11-6 illustrates a search filter load balancing algorithm. In this example, there are three LDAP servers and therefore three distinct routes. LDAP server 1 indexes the uid attribute, LDAP server 2 indexes the cn attribute, and the third LDAP server is a pass-through route.

Figure 11-6 Search Filter Load Balancing

Description of Figure 11-6 follows
Description of "Figure 11-6 Search Filter Load Balancing"

When the proxy receives a search request that contains the uid attribute in its search filter, the search request is routed to LDAP server 1 for better performance. Similarly, if the search filter contains a cn attribute, then the search request is routed to LDAP server 2. All other search requests are routed to the pass-through LDAP server 3.

All other requests, such as ADD, DELETE, MODIFY, and so on can be routed to any LDAP server based on the highest priority. Each search filter route is given a priority. This priority determines the order in which the route are evaluated. The highest priority route filter that matches the search filter is selected to process the request. If all the search filter routes have the same priority, then any route can process the request.

11.2 Data Distribution Using the Proxy

The Oracle Unified Directory distribution feature addresses the challenge of large deployments, such as horizontal scalability, where all the entries cannot be held on a single data source, or LDAP server. Using distribution can also help you scale the number of updates per second.

In a distribution deployment, you must first split your data into smaller chunks. To split the data, you can use the split-ldif command. These chunks of data are called partitions. Typically, each partition is stored on a separate server.

The split of the data is based on one of the following distribution algorithms:

The type of data distribution you choose will depend on how the data in your directory service is organized. Numeric and lexico distribution have a very specific format for distribution. DN pattern can be adapted to match an existing data distribution model.

If a client request (except Add) cannot be linked to one of the distribution partitions, the proxy broadcasts the incoming request to all the partitions, unless a global index catalog has been configured.

However, if the request is clearly identified as outside the scope of the distribution, the request is returned with an error indicating that the entry does not exist. For example, if the distribution partitions includes data with uid's from 1-100 (partition1) and 100-200 (partition2) but you run a search where the base DN is uid=222,ou=people,dc=example,dc=com, the proxy will indicate that the entry does not exist.

Moreover, for the numeric and lexico algorithms, it is the first RDN after the distribution base DN that is used to treat a request. For example, the following search will return an error, as the uid is not the first RDN after the distribution base DN, for example ou=people,dc=example,dc=com.

$ ldapsearch -b "uid=1010,o=admin,ou=people,dc=example,dc=com" "objectclass=*"

Consider the number of partitions carefully. When you define the number of partitions you want in your deployment, you should note that you cannot split and redistribute the data into new partitions without downtime. You can, however, add a new partition with data that has entries outside the initial ones.

For example, if the initial partitions cover data with uids from 1-100 (partition1) and 100-200 (partition2), you can later add a partition3 which includes uids from 200-300. However, you cannot easily split partition1 and partition2 so that partition1 includes uids 1-150 and partition2 includes uids 150-300, for example. Splitting partitions is essentially like reconfiguring a new distribution deployment.

11.2.1 Numeric Distribution

With a distribution using numeric algorithm, the proxy forwards requests to one of the partitions, based on the numeric value of the first RDN after the distribution base DN in the request. When you set up distribution with numeric algorithm, you split the data of your database into different partitions based on a numerical value of the attribute of your choice, as long as the attribute represents a numerical string. The proxy then forwards all client requests to the appropriate partition, using the same numeric algorithm.

For example, you could split your data into two partitions based on the uid of the entries, as illustrated in Figure 11-7.

Figure 11-7 Numeric Distribution Example

Description of Figure 11-7 follows
Description of "Figure 11-7 Numeric Distribution Example"

In this example, a search for an entry with a uid of 1111 is sent to Partition 1, while a search for an entry with a uid of 2345 is sent to Partition 2. Any request for an entry with a uid outside the scope of the partitions defined will indicate that no such entry exists.

Note:

The upper boundary limit of a distribution algorithm is exclusive. This means that a search for uid 3000 in the example above returns an error indicating that the entry does not exist.

Example 11-1 Examples of Searches Using Numeric Distribution Algorithm

The following search will be successful:

$ ldapsearch -b "uid=1010,ou=people,cn=example,cn=com" "cn=Ben"

However, the following searches will indicate that the entry does not exist (with result code 32):

$ ldapsearch -b "uid=1010,o=admin,ou=people,cn=example,cn=com" "objectclass=*"

$ ldapsearch -b "uid=99,ou=people,cn=example,cn=com" "objectclass=*"

The following search will be broadcast, as the proxy cannot determine the partition to which the entry belongs, using the distribution algorithm defined above:

$ ldapsearch -b "ou=people,cn=example,cn=com" "uid=*"

11.2.2 Lexico Distribution

With a distribution using lexico algorithm, the proxy forwards requests to one of the partitions, based on the alphabetical value of the first RDN after the distribution base DN in the request. When you set up distribution with lexico algorithm, you split the data of your database into different partitions, based on an alphabetical value of the attribute of your choice. The proxy then forwards all client requests to the appropriate partition, using the same algorithm.

For example, you could split your data into two partitions based on the cn of the entries, as illustrated in Figure 11-8.

Figure 11-8 Lexico Distribution Example

Description of Figure 11-8 follows
Description of "Figure 11-8 Lexico Distribution Example"

In this example, any requests for an entry with a cn starting with B such as Ben are sent to Partition 1, while requests for an entry with a cn from M-Y are sent to Partition 2.

Note:

The upper boundary limit of a distribution algorithm is exclusive. This means that a search for cn= Zachary in the example above will indicate that no such entry is found. In order to include entries starting with Z in the search boundaries, then you should use the unlimited keyword. For example, cn=[M..unlimited[will include all entries beyond M.

Example 11-2 Examples of Searches Using Lexico Distribution Algorithm

The following search will be successful:

$ ldapsearch -b "cn=Ben,ou=people,cn=example,cn=com" "objectclass=*"

The following search will also be successful, as cn=Ben is the first RDN.

$ ldapsearch -b "uid=1010,cn=Ben,ou=people,cn=example,cn=com" "objectclass=*"

However, the following searches will indicate that the entry does not exist (with result code 32):

$ ldapsearch -b "cn=Ben,o=admin,ou=people,cn=example,cn=com" "objectclass=*"

$ ldapsearch -b "cn=Zach,ou=people,cn=example,cn=com" "objectclass=*"

The distribution cannot determine to which partition the following search belongs and will be broadcast:

$ ldapsearch -b "ou=people,cn=example,cn=com" "cn=*"

11.2.3 Capacity Distribution

With a capacity-based distribution, the proxy sends Add requests based on the capacity of each partition, which is determined by the maximum number of entries the partitions can hold. All other requests are distributed by the global index catalog or by broadcast.

Because the data is distributed to the partitions in a completely random manner, the easiest way to identify on which partition a particular data entry is by using a global index. Global index is mandatory when using capacity distribution. If no global index is set up, all requests other than Add will have to be broadcast. For more information about global indexes, see Section 11.3, "Global Index Catalog" and Section 15.1.7, "Configuring Global Indexes By Using the Command Line."

Figure 11-9 Capacity Distribution Example

Description of Figure 11-9 follows
Description of "Figure 11-9 Capacity Distribution Example"

In the example illustrated in Figure 11-9, Partition 1 has twice the capacity of Partition 2, therefore Partition 1 will receive twice the add requests sent to Partition 2. This way, both partitions should be full at the same time. When all the partitions are full, the distribution will send one request to each partition at each cycle.

11.2.4 DN Pattern Distribution

With a distribution using DN pattern algorithm, the proxy forwards requests to one of the partitions, based on the match between a request base DN and a string pattern. The match is only perform on the relative part of the request base DN, that is, the part after the distribution base DN. For example, you could split your data into two partitions based on a the DN pattern in the uid of the entries, as illustrated in Figure 11-10.

Distribution using DN pattern is more onerous than distribution with numeric or lexico algorithm. If possible, use another distribution algorithm.

Figure 11-10 DN Pattern Distribution Example

Description of Figure 11-10 follows
Description of "Figure 11-10 DN Pattern Distribution Example"

In this example, all the data entries with a uid that ends with 0, 1, 2, 3, or 4 will be sent to Partition 1. Data entries with a uid that ends with 5, 6, 7, 8, or 9 will be sent to Partition 2.

This type of distribution, although using numerical values is quite different from numeric distribution. In numerical distribution, the data is partitioned based on a numerical range, while DN pattern distribution is based on a pattern in the data string.

Distribution using a DN pattern algorithm is typically used in cases where the distribution partitions do not correspond exactly to the distribution base DN. For example, if the data is distributed as illustrated in Figure 11-11, the data for Partition 1 and Partition 2 is in both base DN ou=people,ou=region1 and ou=people,ou=region2. The only way to distribute the data easily is to use the DN pattern.

Figure 11-11 Example of Directory Information Tree

Description of Figure 11-11 follows
Description of "Figure 11-11 Example of Directory Information Tree"

Example 11-3 Example of DN Pattern Algorithm Split by Region

If the deployment of the information is based in two geographical locations, it may be easier to use the DN pattern distribution to distribute the data. For example, if employee numbers were 4 digit codes, where the first digit indicated the region, then you could have the following:

Region 1 Region 2

1000

2000

1001

2001

1002

2002

1003

2003

1004

2004

1005

2005

1006

2006

1007

2007

1008

2008

1009

2009

1010

2010

...

...


In order to spread the load of data, the entries in each location are split over two servers, where Server 1 contains all entries that end with 0, 1, 2, 3, and 4, while Server 2 contains all the entries that end with 5, 6, 7, 8, and 9, as illustrated in Figure 11-10.

Therefore, a search for DN pattern 1222 would be sent to partition 1, as would 2222.

11.3 Global Index Catalog

A global index catalog can be used with a distribution deployment. If you are configuring a capacity based distribution, you must have a global index, with DN indexed. The global index catalog maps the entries to the distribution partition in which the data is held. When the proxy receives a request from the client, the distribution looks up the attribute entry in the global index catalog, and forwards the client request to the correct partition. This diminishes the need for broadcasts. Moreover, if a modify DN request is made, the global index catalog will ensure that the entry is always found.

A global index catalog maps the entries based on specific attributes, such as employee number or telephone number. The value of the attribute to be indexed must be unique across all the entries. You cannot use a global index to map entries based on country, for example, as that information is not unique.

If you index an attribute whose values are not unique, the proxy server might be unable to return all the requested entries. Say, for example, that you index the mail attribute, whose values are not necessarily unique. You now add the following two entries in sequence:

In this situation, the global index mail keeps reference to the second entry only. A search with the filter (mail=joe.smith@example.com) will return only the second entry, uid=user.2.

A global index catalog can include several global indexes. Each global index maps a different attribute. For example, you can have one global index catalog called GI-catalog, which includes a global index mapping the entries based on the telephone number and one mapping the entries based on the employee number. This means that you can forward client requests to the right partition using either the telephone number or the employee number.

Global index catalogs and global indexes are created and configured using the gicadm command. For more information see Section 15.1.7, "Configuring Global Indexes By Using the Command Line" and Appendix A, "gicadm."

The global indexes can be populated with data from LDIF files. The data from one LDIF file can be split into partitions using the split-ldif command. For more information, see Appendix A, "split-ldif."

A global index catalog should be replicated to avoid a single point of failure. For information on replicating the global index catalog, see Section 15.1.7.2, "Replication of Global Index Catalogs."

Example 11-4 Using a Global Index Catalog for Telephone Numbers

A typical example of a unique attribute which can be used to create a global index is a telephone number: the value of the attribute is unique, that is, only one person (employee, for example) can have that telephone number.

In the example below, the entries in the database have been split based on the telephone number. The global index includes the following information:

Value Partition ID

4011233

1

4011234

1

7054477

2


The global index does not store the name of the employees, location, and other attribute values that may be associated to the telephone number. It only maps the attribute indexed to the partition. The data associated to the indexed value (here telephone number) is stored in the remote LDAP server.

If an employee has multiple phone numbers, these are regarded as multi-valued entries. In this case, if the global index is created based on the telephone number, there will be two global index entries that will result in finding one employee, say Ben Brown.

In the example above, employee Ben Brown could have both telephone number 4011233 and 7054477 assigned to him. In this case, a search on one of Ben Brown's telephone number would return the correct partition, and all the information associated to the telephone number, including the name Ben Brown, regardless that he has two phone numbers attributed to him.

11.4 DN Renaming Using the Proxy

Each entry in a directory is identified by a DN and a set of attributes and their values. Sometimes, the DN and the attributes defined on the client side do not map with the DN and the attributes defined on the server side. For instance, an organization, Example A contains dc=parentcompany, dc=com entries. It acquires another organization, Example B. Example B contains dc=newcompany, dc=com entries. Therefore, dc=newcompany, dc=com must be renamed to dc=parentcompany, dc=com for the existing client applications to work correctly.

You can define a DN renaming workflow element to rename DNs to values that match the server side. When a client makes a request, the DNs and attributes are renamed to match those in the server. When the result is returned to the client, the DN and attributes are changed back to match what the client has requested.

11.4.1 How the DN Renaming Workflow Element Works

Oracle Unified Directory provides a DN renaming workflow element that allows you to transform the content of a Directory Information Tree (DIT) into another DIT with a different base DN. When an operation (Add, Bind, Delete, Modify, and so on) goes through a DN renaming workflow element, its parameters are transformed according to the DN renaming configuration to transform the virtual entries into real entries.

Figure 11-12 illustrates how DN renaming is performed using the proxy.

The client expects ou=myorg, dc=server, dc=com entries. However, the LDAP server contains ou=people, dc=server, dc=com entries. The proxy renames the DNs by making use of the DN renaming workflow element.

In this example, the real entries ou=people, dc=server, dc=com are seen as ou=myorg, dc=server, dc=com entries from the client side.

The DN renaming transformation is applicable to the following objects:

  • DN of the entry: For example, the real entry on the LDAP server dn:uid=user, ou=people, dc=server, dc=com is transformed into a virtual entry dn:uid=user, ou=myorg, dc=server, dc=com from the client perspective.

  • Attributes of the entry that contain DNs: For example, the server-side value of the manager attribute of an entry with an objectclass inetorgpersonmanager: manager:uid=mgr, ou=people, dc=server, dc=com is transformed into the value manager:uid=mgr, ou=myorg, dc=server, dc=com on the client side.

Note:

You can apply the transformation to all the user attributes of the entries, define a restricted list of attributes to which the operation applies, or define a restricted list of attributes to which the operation does not apply.

11.5 RDN Changing

Oracle Unified Directory enables you to rename or replace RDN values from the source directory to Oracle Unified Directory using the RDNChanging configuration.

Figure 11-13 illustrates how DN renaming is performed using the proxy.

Figure 11-13 RDN Changing

Description of Figure 11-13 follows
Description of "Figure 11-13 RDN Changing"

Note:

The relative distinguished name (RDN) is the leftmost element in an entry DN. For example, the RDN for uid=Marcia Garza,ou=People,dc=example,dc=com is uid=Marcia Garza. You can only change the leftmost element in an entry DN.

The RDNChanging configuration has the following parameters:

objectclass

Identifies the objectclass type that RDN renaming is performed on. The default setting is person.

replace-value

True or False: Indicates whether the value of original RDN value in the client view (identified by the source-rdn parameter) should be replaced by the value of the new RDN value (identified by the client-rdn parameter). The default setting is true.

Note:

When the value is set to true, and an entry has multiple values for the new RDN attribute, then Oracle Unified Directory uses the first value in RDN.

source-rdn

Identifies the original RDN attribute name from the source directory to be replaced or renamed in Oracle Unified Directory.

client-rdn

Identifies the new RDN attribute name to be used in Oracle Unified Directory and replaces the attribute name identified by the source-rdn configuration parameter.

dn-attributes

List of attributes with DNs to perform RDN renaming on. The default list of attributes are member, manager, and owner.

11.6 Understanding the Transformation Framework

Oracle Unified Directory supports transformation of data through the definition of workflow elements. By creating an instance of workflow element you can display physical data in a different way. This chapter describes how transformation in Oracle Unified Directory occurs and contains the following topics:

11.6.1 Overview of Transformation

The data structure of an LDAP client application may differ from the data structure of the LDAP repository. They may differ on the schema (different types of attribute in the entries) or the values (same attribute name with different semantic of values). This is where you need transformation.

A transformation performs a specific action in a certain direction. You have to specify the transformations that you need and define these on an existing workflow elements.

This section contains the following topics:

11.6.1.1 Transformation Models

The direction of transformation that is whether the transformation is applied during the request, during the response, or both determines the transformation model.

Transformations can be categorized into the following types:

11.6.1.1.1 Read Transformations

The read transformation is the most common transformation. 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.

Figure 11-14 illustrates the concept of a read transformation.

Figure 11-14 Read Transformation

Description of Figure 11-14 follows
Description of "Figure 11-14 Read Transformation"

Consider a scenario of an organization that has a legacy application whose function is to display person entries. The application does not support entries that do not contain an email attribute. The physical data source has been upgraded and the email attribute no longer exists for person entries.

You need to apply a transformation here, which is to add the email attribute during the search response. This transformation changes the entry that is read from the data source and adds an email attribute whose value is firstname.surname@mycompany.com. No reverse transformation is required and the physical data is not changed.

11.6.1.1.2 Write Transformations

A write transformation is applied during the request, but not during the response. A write transformation modifies data provided by the client before storing it in the backend.

Figure 11-15 illustrates the concept of a write transformation.

Figure 11-15 Write Transformation

Description of Figure 11-15 follows
Description of "Figure 11-15 Write Transformation"

Consider a scenario of an organization that has a legacy application whose function is to add person entries to a data source. The application adds the entries without the email attribute. The physical data source has been upgraded and the email is now a mandatory attribute for person entries. You need to apply a transformation here, which is to add the email attribute during the add request. This transformation changes the entry that is written to the database. No reverse transformation is required.

11.6.1.1.3 Mapping Transformations

The mapping transformation is the most common transformation. It is bidirectional in the sense that it is first applied during the request, and the reverse is applied during the response. These transformations are called mappings, because 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.

Figure 11-16 illustrates the concept of a mapping transformation.

Figure 11-16 Mapping Transformation

Description of Figure 11-16 follows
Description of "Figure 11-16 Mapping Transformation"

Consider a scenario of an organization, which has a physical data source that contains entries with the attributes surname and firstname. The organization has a client application that requires entries to have a cn (common name) attribute of the form firstname surname.

The client application sends a search request for an entry of the form cn=Joe Smith. A transformation is defined that extracts the firstname and surname during this request and transforms the request to one of the form surname=Smith, firstname=Joe. 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=Joe Smith, which it understands.

This request is transformed to be of the form surname=Smith, firstname=Joe.

11.6.1.2 Implementing Transformation in Oracle Unified Directory

Oracle Unified Directory is an LDAP server that supports transformations in a proxy server.

To implement transformations, you need to:

  • Create an instance of a workflow element of type transformations.

  • Insert the transformation workflow element in the desired workflow elements list.

For more information about the architecture of Oracle Unified Directory, see Section 4.2, "Architecture of Oracle Unified Directory."

A transformation workflow element instance is essentially a data view on which certain transformation actions are defined.

11.6.2 Components of Transformation

This section describes the components for configuring the workflow elements for transformation. It contains the following topics:

11.6.2.1 Transformation Types

You can configure the workflow element of type transformations with the following set of transformations:

Note:

Here:

  • Client side: Refers to the side where the Oracle Unified Directory server interacts with the client application.

  • Source side: Refers to the side where the Oracle Unified Directory server interacts as a data server with its local data source, or as a proxy server with a remote server.

  • Inbound direction: Refers to the direction where transformations are applied from the client to the source.

  • Outbound direction: Refers to the direction where transformations are applied from the source to the client.

This section contains the following topics:

11.6.2.1.1 addOutboundAttribute Transformation Type

This transformation adds a virtual attribute or value(s) to entries returned to the client during a SEARCH operation, when the list of attributes in the request is either undefined (all) or when it contains this attribute.

When you cannot determine if an entry already contains a virtual attribute, the conflict-behavior parameter decides which of the following policy will apply:

  • The virtual value is not added

  • The virtual value is added and merged with the existing values

  • The virtual value replaces the existing one

If you are aware that the virtual attribute is searchable in the source repository, which implies some entries in the source repository contain the virtual attribute and searches are optimized on this attribute, and if the flag virtual-in-source is set then the transformation process forwards the virtual attribute to the source repository in the SEARCH REQUEST filter. Usually, the virtual attribute is not forwarded to the source repository. When it is set to FALSE, search requests are optimized for common cases, which implies virtual attributes not expected to be in the source repository.

Note:

You must keep in mind that the source schema check is applied when the virtual attribute is expected to appear in ADD or MODIFY requests. Therefore, it is recommended to configure the schema of the source to accept the virtual attribute. Otherwise, disable schema checking.

Table 11-1 describes the parameters of addOutboundAttribute transformation type.

Table 11-1 Parameters of addOutboundAttribute Transformation Type

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

Name of the client virtual attribute and the value definitions of the client virtual attribute

client-attribute

S

M

string

For more information, see Section 11.6.2.3, "Defining Attribute Values for Transformation."

For example, displayName=%cn% publishes the attribute displayName with value of cn.

Conflict behavior policy

conflict-behavior

S

O [default=merge-real-and-virtual]

merge-real-and-virtual

real-overrides-virtual

virtual-overrides-real

Virtual in source policy

virtual-in-source

S

O [default = FALSE]

TRUE, FALSE

Condition based on a filter that the entry must match

entry-match-filter

S

O [default = apply to all entries processed by the workflow element]

LDAP filter

Condition based on DN that must be an ascendant

entry-parent-suffix

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

excluded-operation

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY...)


11.6.2.1.2 filterOutboundAttribute Transformation Type

This transformation removes an attribute or value(s) from entries received from the source before sending to the client.

Table 11-2 describes the parameters of filterOutboundAttribute transformation type.

Table 11-2 Parameters of FilterOutboundAttribute Transformation Type

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

Name of the source virtual attribute and the value definitions of the client virtual attribute

source-attribute

S

M

string

For more information, see Section 11.6.2.3, "Defining Attribute Values for Transformation."

For example, certificate=verisign filters the verisign value from the certificate attribute.

Condition based on a filter that the entry must match

entry-match-filter

S

O [default = apply to all entries processed by the worflow element]

LDAP filter

Condition based on DN that must be an ascendant

entry-parent-suffix

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

excluded-operation

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY...)


11.6.2.1.3 addInboundAttribute Transformation Type

This transformation adds a virtual attribute or value(s) to entries received from the client while performing the ADD operation before forwarding the data to the source.

When you cannot determine if an entry already contains a virtual attribute, the conflict-behavior parameter decides which of the following policy will apply:

  • The virtual value is not added

  • The virtual value is added and merged with the existing values

  • The virtual value replaces the existing one

Table 11-3 describes the parameters of addInboundAttribute transformation type.

Table 11-3 Parameters of addInboundAttribute Transformation Type

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

Name of the source virtual attribute and the value definitions of the source virtual attribute

source-attribute

S

M

string

For more information, see Section 11.6.2.3, "Defining Attribute Values for Transformation."

For example, email={%cn%.%sn%@mycompany.com}writes the attribute email with value derived from attributes cn and sn.

Conflict behavior policy

conflict-behavior

S

O [default=merge-real-and-virtual]

merge-real-and-virtual

real-overrides-virtual

virtual-overrides-real

Condition based on a filter that the entry must match

entry-match-filter

S

O [default = apply to all entries processed by the worflow element]

LDAP filter

Condition based on DN that must be an ascendant

entry-parent-suffix

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

excluded-operation

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY)


11.6.2.1.4 filterInboundAttribute Transformation Type

This transformation removes an attribute or value(s) from entries (and modifications) received from the client on a ADD (and MODIFY) before forwarding to the source.

Table 11-4 describes the parameters of filterInboundAttribute transformation type.

Table 11-4 Parameters of FilterInboundAttribute Transformation Type

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

Name of the client virtual attribute and the value definitions of the client virtual attribute

client-attribute

S

M

string

For more information, see Section 11.6.2.3, "Defining Attribute Values for Transformation."

For example, certificate=verisign filters the value verisign of the attribute certificate.

Similarly, secondarylocation=%primarylocation% filters the values of secondarylocation when it matches the values of primarylocation.

Condition based on a filter that the entry must match

entry-match-filter

S

O [default = apply to all entries processed by the worflow element]

LDAP filter

Condition based on DN that must be an ascendant

entry-parent-suffix

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

excluded-operation

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY...)


11.6.2.1.5 mapAttribute Transformation Type

The transformation can rename or revalue a client attribute to one source attribute in both directions.

Table 11-5 describes the parameters of mapAttribute transformation type.

Table 11-5 Parameters of mapAttribute Transformation Type

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

Name of the client attribute and the value definitions of the mapping from the client virtual attribute to the source virtual attribute

client-attribute

S

M

string

For more information, see Section 11.6.2.3, "Defining Attribute Values for Transformation."

For example, displayName=%cn% publishes displayName attribute replacing it with the value of cn attribute, and writes cn attribute replacing it with the value of displayName attribute.

Virtual in source policy

virtual-in-source

S

O [default = FALSE]

TRUE, FALSE

Conflict behavior policy

conflict-behavior

S

O [default=merge-real-and-virtual]

merge-real-and-virtual

real-overrides-virtual

virtual-overrides-real

Condition based on a filter that the entry must match

entry-match-filter

S

O [default = apply to all entries processed by the worflow element]

LDAP filter

Condition based on DN that must be an ascendant

entry-parent-suffix

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

excluded-operation

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY,...)


11.6.2.2 Transformation Conditions

You can configure the Transformations workflow element with a set of conditions. Conditions are properties (attributes) that can be set either on a transformations-workflow-element or on an individual transformation.Transformation works only when LDAP request matches all conditions and all conditions set at the level of workflow element.

The following conditions are applicable for implementing transformation:

  • Conditions can be configured to rules whether transformations apply or not.

  • Conditions can be set on the transformations-workflow-element. In this situation, conditions apply for all transformation set on the workflow-element and are evaluated prior to eventually processing each transformation.

  • Conditions can also be set on each individual transformation and are evaluated prior to eventually processing this transformation.

In this sense, conditions can be broadly categorized as follows:

11.6.2.2.1 Parent Suffix

This condition is applicable for transformations applied only for LDAP operations that target an entry for which name is under one of the parent suffixes specified.

When no condition of this type is configured, then transformation applies to all entries processed.

11.6.2.2.2 Entry Match Filter

This condition is applicable for transformations applied on LDAP operations only for entries that match the provided filter.

When no condition of this type is configured, then transformation applies to all entries processed.

11.6.2.2.3 Excluded LDAP Operation

This condition specifies a list of multi-valued attributes, where each attribute is an LDAP operation that should not be impacted by the transformation. It allows you to disable the action of the transformation (when it has one) on each LDAP protocol message.

When no condition of this type is configured, then transformation applies to all LDAP operations normally impacted by this type of transformation.

11.6.2.3 Defining Attribute Values for Transformation

An attribute value allows you to define the value of a virtual attribute during transformation. This value can either be a default value, or rule that creates the value from other attribute values.

For addInboundAttribute, addOutboundAttribute, and mapAttribute, you must configure the values of the virtual attribute added. For filterInboundAttribute and filterOutboundAttribute, the values you intend to filter may be configured.

An attribute can derive its value from the following:

11.6.2.3.1 Constant

It is used to generate an attribute with a static default value or to filter a static value of an attribute.

For example, the property source-attribute:mycompany=Acme is used to provide a default company name.

dsconfig --create-transformation \
--type add-inbound-attribute \
--set source-attribute:mycompany=Acme \
--transformation-name virtDeptName \
11.6.2.3.2 Value of Another Attribute

It is used to create a new attribute from an existing attribute in the entry that is being processed or to filter a value taken from another attribute using the %inputAttrName% syntax.

For example, the property source-attribute:displayName=%cn% specifies that the value of the new attribute must be taken from the value of the cn attribute.

dsconfig --create-transformation \
--type add-inbound-attribute \
--set source-attribute:displayName=%cn% \
--transformation-name virtDeptName \

Note:

You must keep in mind that another virtual attribute generated in the same transformations-workflow-element should not be referenced, because the evaluation order is not guaranteed.

11.6.2.3.3 Regular Expressions

It is used to create an attribute value or to filter an attribute value by manipulating the value of an existing attribute using the {expression} syntax.

For example, the property client-attribute:mail={%cn%.%sn%@mycompany.com} is a regular expression that is used for deriving an attribute by combining the values of existing attributes.

dsconfig create-transformation \
--type add-outbound-attribute \
--set client-attribute:mail={%cn%.%sn%@mycompany.com} \
--transformation-name virtDeptName \
11.6.2.3.4 Values Mapping

It is used for defining virtual values as a mapping of values of another attribute using the virtAttrName=%refAttrName%(virtValue1,refValue1)(virtValue2,refValue2) syntax.

For the virtAttrName parameter, the transformation adds or filters values extracted from refAttrName. If refAttrName matches refValue1, then transformation processes either add or filter for virtValue1. In the values provided, characters '(', ')', ',' and '\'must be escaped using '\' character.

For example, consider an organization with several departments where department name is returned for the retrieved department ID, such as Department:1–Marketing, 2–Sales, 3–Finance and so on. But, when deptId is 1, the value returned for deptName is Marketing. When deptId is 2,the value for deptName is Sales. Similarly, when deptId is 3, the value returned for deptName is Finance.

dsconfig --create-transformation \
--type add-outbound-attribute \
--set client-attribute:deptName=%deptId%(Marketing,1)(Sales,2)(Finance,3) \       
--transformation-name virtDeptName
11.6.2.3.5 Multi-valued Virtual Attributes

It is used to specify a virtual multi-valued attribute using the virtAttrName=virtAttrValue1=virtAttrValue2= syntax.

dsconfig --create-transformation \
--type add-outbound-attribute \
--set client-attribute:countriesResp=France=Germany=Italy \
--transformation-name virtCountriesRep

11.6.3 Configuring Transformation

This section describes how to configure the transformation workflow element, and contains the following topics:

11.6.3.1 Overview of the Configuration Model

The transformations-workflow-element and transformations are the backbone entities for configuring transformation.

The Transformations workflow element is a container that contains a list of references to transformations. One transformation can be reused by multiple transformation-workflow-elements. Conditions are properties (attributes) that can be set either on a transformations-workflow-element or on a transformation.

Table 11-6 describes the parameters that you can configure for a transformations-workflow-element.

Table 11-6 Parameters to Configure for a transformations-workflow-element

Parameter dsconfig CLI Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values

List of transformation types

See Section 11.6.2.1, "Transformation Types" for more information.

transformation object (association)

M

M

Reference to a transformation

Condition based on a filter that the entry must match

See Section 11.6.2.2.2, "Entry Match Filter" for more information.

entry-match-filter property

S

O [default = apply to all entries processed by the worflow element]

LDAP filter

Condition based on DN that must be an ascendant

See Section 11.6.2.2.1, "Parent Suffix" for more information.

entry-parent-suffix property

M

O [default = apply to all requests processed by the workflow element]

DN

Condition to exclude operations in the operation processing

Section 11.6.2.2.3, "Excluded LDAP Operation" for more information.

excluded-operation property

M

O [default = apply to all LDAP operations]

enumerated (ADD, MODIFY...)


You cannot configure the order in which the transformations should work. For instance, you define a transformation-workflow-element that uses transformation A and transformation B. But, you cannot determine if an entry is first processed by transformation A and then by transformation B. It can be B before A.

If you need to define the order in which transformation should occur, for example transformation A should happen before transformation B, then it is recommended that you first create a transformation-workflow-element that uses transformation A. Next, create another transformation-workflow-element that uses transformation B. Now, place the second transformation-workflow-element after the first transformation-workflow-element.

Figure 11-17 illustrates a high-level configuration model.

Figure 11-17 Configuration Model

Description of Figure 11-17 follows
Description of "Figure 11-17 Configuration Model"

11.6.3.2 Example of Configuring Transformation Using CLI

The example in this section describes how to create transformations with dsconfig CLI, create a transformation workflow element, add transformations, and associate conditions.

Perform the following steps to configure transformation:

  1. Create a first transformation of type filter-outbound-attribute.

    $ dsconfig --create-transformation -X -n -Q -p -D cn="directory manager" -j pwd-file \
    --set source-attribute:description \
    --type filter-outbound-attribute\
    --transformation-name fodescription
    
  2. Create another transformation of type add-outbound-attribute.

    $ dsconfig --create-transformation -X -n -Q -p -D cn="directory manager" -j pwd-file  \ 
    --set client-attribute:legacyemail=%cn%.%sn%@mycompany.com \ 
    --type add-outbound-attribute \ 
    --transformation-name legacyemail
    
  3. Create the transformations-workflow-element with the first transformation, and add it to the processing flow.

    $ dsconfig --create-workflow-element -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --set transformation:legacyemail \ 
    --set set next-workflow-element:pxywfe \ 
    --type transformations \ 
    --element-name trsfwfe
    
    $ dsconfig --set-workflow-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --workflow-name pxywf \ 
    --set workflow-element:trsfwfe
    
  4. Add the second transformation to the workflow element.

    $ dsconfig --set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --element-name trsfwfe \ 
    --add transformation:fodescription
    
  5. Define the transformation criteria, which is that the transformation will occur only under cn=users.

    $ dsconfig --set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --element-name trsfwfe \ 
    --set entry-parent-suffix:cn=users,dc=oracle
    
  6. Set that transformations will happen only for users located in Paris.

    $ dsconfig --set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --element-name trsfwfe \ 
    --set entry-match-filter:l=Paris
    
  7. Create a new mapping transformation and add it to the workflow element.

    $ dsconfig --create-transformation -X -n -Q -p -D cn="directory manager" -j pwd-file  \ 
    --set client-attribute:faxnum=%facsimileTelephoneNumber% \ 
    --type map-attribute \ 
    --transformation-name mapfax 
    
    $ dsconfig --set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --element-name trsfwfe \ 
    --add transformation:mapfax
    
  8. Set that this transformation will happen only for persons.

    $ dsconfig --set-transformation-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
    --transformation-name mapfax \ 
    --set entry-match-filter:\(objectclass=person\)