1. Administering Oracle Unified Directory
  2. Oracle Unified Directory Concepts and Architecture
  3. Understanding the Proxy, Distribution, and Virtualization Functionality

12 Understanding the Proxy, Distribution, and Virtualization Functionality

Understand about the conceptual overview of the Oracle Unified Directory functionality that enables you to use a proxy server for various types of deployments.

This functionality includes configurable workflow elements and an extensible plug-in API that you can use to work with data residing on remote and distributed data sources or servers.

This chapter includes the following sections:

Note:

Before reading this chapter, review Introduction to Oracle Unified Directory and Understanding Deployments Using the Proxy Server for a better understanding of the concepts described here.

For more information about configuring the features and functionality described in this chapter, see the chapters in Configuring Proxy, Distribution, and Virtualization Functionality

12.1 Accessing Remote Data Sources

Remote data is accessed either in a relational database management system (RDBMS) such as an Oracle Database or a remote LDAP directory server.

The following topics describe how to access remote data:

For configuration information, see Configuring Access to Remote Data Sources.

12.1.1 Enabling LDAP Clients to Access Identity Data Stored in an RDBMS

The RDBMS workflow element enables LDAP clients to access identity data stored in a relational database management system (RDBMS) using the LDAP protocol.

The topics in this section include:

For information about configuring an RDBMS workflow element and its supporting components, see Configuring Access to Identity Data Stored in an RDBMS.

12.1.1.1 Understanding How to Use an RDBMS Workflow Element

The RDBMS workflow element allows you to create a bridge between Oracle Unified Directory LDAP clients and an RDBMS such as an Oracle Database. A deployment can use an RDBMS workflow element implementation to meet the following requirements:

  • The deployment stores some identity data in an LDAP directory server, but it also has additional data stored in an RDBMS. LDAP clients want to integrate data from both sources into aggregate virtual views.

  • LDAP clients want to use the LDAP protocol to read and write the identity data stored in both the LDAP directory server and the RDBMS. These clients do not want to use SQL queries and commands to access the RDBMS data.

12.1.1.2 About RDBMS Workflow Element Features

An RDBMS workflow element implementation supports the following features:

  • You can configure a connection to most RDBMS databases that support JDBC. For a list of supported databases, check the Oracle Unified Directory 11g Release 2 (11.1.2.3) Certification Matrix.

  • You can map LDAP object classes and attributes to SQL tables and columns in the RDBMS to create virtual views of the RDBMS data. You are not required to make any modifications to the RDBMS.

  • You can use the following LDAP operations. These operations are translated to the equivalent SQL queries to access data stored in the RDBMS:

    • BIND

    • ADD

    • DELETE

    • MODIFY

    • MODIFYDN

    • SEARCH

    Note:

    In the current release, the RDBMS workflow element does not support LDAP write operations (add, modify, or delete) when entries are built from multiple SQL tables.

  • You can control access to the virtual views of the RDBMS data using an access control group and virtual ACIs based on LDAP client identities.

12.1.1.3 Caching RDBMS Workflow Element

The RDBMS workflow element maintains an in-memory cache containing data already accessed from the RDBMS. By default, this cache is enabled.

The default (and recommended) caching-scheme is soft-weak. This scheme holds soft references to the database entries and enables optimal caching of objects while still allowing the JVM to garbage collect them if memory is low. This scheme also maintains a most frequently used subcache containing soft references to the objects, which allows the objects to be garbage collected except for a fixed number of the most recently used objects.

To specify a different caching scheme for the RDBMS workflow element, use dsconfig. For example: 

$ dsconfig set-workflow-element \
--element-name ORCL1 \
--set caching-scheme:full

When data entries targeted by the proxy are modified by external means (for example, by an application or a user directly accessing the database using an SQL statement), the changes might not be reflected in the RDBMS workflow element. If you require strong data consistency, change the caching scheme or disable caching altogether by setting the caching-scheme property in the RDBMS workflow element.

For example, to disable caching, set the caching-scheme property to none: 

$ dsconfig set-workflow-element \
--element-name ORCL1 \
--set caching-scheme:none

For more information about the RDBMS workflow element caching properties, including the caching schemes you can configure, see the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

12.1.1.4 Configuring RDBMS Workflow Element
12.1.1.4.1 Configuring Oracle Unified Directory Proxy Server

The RDBMS workflow element requires an Oracle Unified Directory proxy server as the interface between the LDAP clients and the RDBMS. The proxy server uses the following elements to communicate with the RDBMS:

  • An RDBMS extension manages the connectivity with the remote server through JDBC by periodically checking the response from the remote peer and providing valid connections maintained by the connection pool.

  • An RDBMS workflow element retrieves the connections from the RDBMS extension element, performs mapping between LDAP entries and SQL tables, and executes operations received from the LDAP clients.

To create a proxy server, you run the oud-proxy-setup or oud-proxy-setup.bat script. These scripts require a supported Java installation (JRE 7 or JDK 7). Your JAVA_HOME environment variable should point to this installation.

12.1.1.4.2 Installing JDBC Driver JAR File

An RDBMS workflow element implementation relies on the JDBC standard to communicate with the RDBMS, so you must install the JDBC driver JAR file that corresponds to the RDBMS you are using.

12.1.1.4.3 Creating RDBMS Workflow Element and Supporting Components

Communication with the RDBMS requires the RDBMS workflow element and its components. To create and configure these components, you perform the following tasks:

  1. Create an RDBMS extension, RDBMS workflow element, and a workflow associated with the RDBMS workflow element.
  2. Assign the workflow associated with the RDBMS workflow element to a network group.
  3. Configure LDAP-SQL mappings for the LDAP attributes and object classes that correspond to the SQL tables and columns you want to access in the RDBMS.
12.1.1.4.4 Configuring Access Control Group and Virtual ACIs

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

Access control to the virtual data from the RDBMS is configured using an access control group with virtual ACIs based on the LDAP client identities. Virtual ACIs are created and stored on the Oracle Unified Directory proxy instance.

To configure access control to the virtual data, you perform the following tasks:

  1. Create an access control group for the workflow associated with the RDBMS workflow element.
  2. Create virtual ACIs based on the LDAP client identities and add these virtual ACIs to the access control group created in Step 1.

Note:

Your access control strategy for the virtual data from the RDBMS depends on your corporate policies, so you must create virtual ACIs to follow those policies.

For more information, see Understanding Virtual Access Control Instructions.

12.1.2 Understanding How to Enable Communication with a Remote LDAP Server

You can enable communication with a remote LDAP server by using LDAP Server Extension and Proxy LDAP Workflow elements.

To enable communication between a proxy instance and a remote LDAP server:

  • LDAP Server Extension: This element manages connectivity with a remote server by periodically checking the response from the remote peer and providing valid connections maintained by the connection pool.

  • Proxy LDAP Workflow Element: This element retrieves connections from the LDAP server extension element and executes operations received from the user as defined in the configured mode.

Note:

12.2 Overview of Load Balancing Using the Proxy

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

Note:

For information about how to configure load balancing, see Configuring Load Balancing Using the Proxy.

This section contains the following topics:

12.2.1 Understanding Load Balancing Using the Proxy

In a load balancing deployment, the requests are routed to one of the data sources based on the load balancing algorithm set. There are five load balancing algorithms: Failover, Optimal, Proportional, Saturation and Search Filter.

You can choose one of the following load balancing algorithms:

  • Failover. Several remote LDAP server handle requests, based on the priority configured on a server, for a given operation type. When there is a failure, requests are sent to the server with the next highest priority for that operation type.

  • Optimal. There is no priority between the different remote LDAP servers. The LDAP server with the lowest saturation level is the one that handles the requests. The saturation level of the remote LDAP servers is regularly reevaluated, to ensure that the best route is chosen.

  • Proportional. All the remote LDAP servers handle requests, based on the proportions (weight) set.

  • Saturation. There is one main LDAP server that handles all requests, until the saturation limit is reached.

  • Search Filter. Several LDAP servers are deployed, and handle requests based on certain attributes in the request search filter.

12.2.2 Understanding 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 12-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 12-1 Failover Load Balancing Example

Description of Figure 12-1 follows
Description of "Figure 12-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 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 Modifying the LDAP Data Source Monitoring Connection Properties.

12.2.3 Understanding Optimal Load Balancing

Understand optimal load balancing concepts and learn how to determine saturation level.

The following sections provide an overview of optimal load balancing concepts and how to determine saturation level:

12.2.3.1 Overview of 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 12-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 12-2 Optimal Load Balancing Example

Description of Figure 12-2 follows
Description of "Figure 12-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 Setting the Saturation Precision for the Optimal or Saturation Algorithm.

12.2.3.2 Determining Saturation Levels

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.

12.2.4 Understanding 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 12-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 12-3 Proportional Load Balancing Example

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

You can configure a specific weight for each type of client operation, as illustrated in Figure 12-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 12-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 12-4 Proportional Load Balancing with Request Specific Management

Description of Figure 12-4 follows
Description of "Figure 12-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 12-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 Modifying Load Balancing Properties.

12.2.5 Understanding Saturation Load Balancing

Understand, with an example, about Saturation Load Balancing and what happens with saturation load balancing algorithm. 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 12-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 12-5 Saturation Load Balancing Example

Description of Figure 12-5 follows
Description of "Figure 12-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 Determining Saturation Levels.

12.2.6 Understanding Search Filter Load Balancing

Understand about search filter load balancing with the following example.

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 12-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 12-6 Search Filter Load Balancing

Description of Figure 12-6 follows
Description of "Figure 12-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.

12.3 Overview of 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.

This section contains the following topics:

12.3.1 Understanding Data Distribution Using the Proxy

You can understand about data distribution using the proxy. 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

Note:

For information about configuring data distribution, see Configuring Distribution Using the Proxy.

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

  • Numeric. Entries are split into partitions and distributed based on the numeric value of the naming attribute (for example uid).

  • Lexico. Entries are split into partitions and distributed based on the alphabetical value of the naming attribute (for example cn).

  • Capacity. Entries are added to a partition based on the capacity of each partition. This algorithm is used for Add requests only. All other requests are distributed by the global index catalog or by a broadcast.

  • DN pattern. Entries are split into partitions and distributed based on the pattern (value) of the entry DN.

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 defining the number of partitions for your deployment, be aware 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.

12.3.2 Understanding Numeric Distribution

Understand numeric distribution with the following example. 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, if 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 12-7.

Figure 12-7 Numeric Distribution Example

Description of Figure 12-7 follows
Description of "Figure 12-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.

Consider the 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=*"

12.3.3 Understanding Lexico Distribution

Understand Lexico distribution with the following example. 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 12-8.

Figure 12-8 Lexico Distribution Example

Description of Figure 12-8 follows
Description of "Figure 12-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. If you want to include entries that start with Z in the search boundaries, then use the unlimited keyword. For example, use cn=[M..unlimited[to include all entries beyond M.

Consider the 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=*"

12.3.4 Understanding Capacity Distribution

Understand Capacity distribution with the following example. 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 Understanding the Global Index Catalog and Configuring Global Indexes Using the Command Line.

Figure 12-9 Capacity Distribution Example

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

In the example illustrated in Figure 12-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.

12.3.5 Understanding DN Pattern Distribution

Understand DN Pattern distribution with the following example. 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 the DN pattern in the uid of the entries, as illustrated in Figure 12-10.

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

Figure 12-10 DN Pattern Distribution Example

Description of Figure 12-10 follows
Description of "Figure 12-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 12-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 12-11 Example of Directory Information Tree

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

Consider the 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

...

...

To spread the data load, 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 12-10.

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

12.3.6 Understanding Union Workflow Element

The Union workflow element aggregate several DITs into a virtual unified DIT.

Topics:

12.3.6.1 Overview of Union Workflow Element

The Union workflow element enables you to customize the bind and search routing policies.

For example, if an LDAP bind request satisfies multiple partitions to route the request to, then the Oracle Unified Directory always routes the request to the partition with highest priority. Consequently, authentication for users provisioned in other partition' data source would fail.

This workflow allows the bind operation to fall through the list of all eligible partitions that have been configured in this workflow. Similarly, it also provides a search policy that allows the search to continue to the next partition only when an entry is not returned from one partition.

12.3.6.2 Configuration Parameters for Union Workflow Element

Learn about the various Union workflow element configuration parameters, their names, descriptions, and functionality.

Property Description Mandatory or Optional Value

base-dn

The base DN of the virtual unified DIT. A virtual unified DIT is an aggregation of one or more partitons.

Mandatory

A valid DN. For example, ou=people,dc=example,dc=com

enabled

This parameter Indicates whether the workflow element is enabled for use in the server. If a workflow element is not enabled, then its contents are not accessible when processing operations.

Mandatory

true or false

cache-size

Defines the maximum number of entries that can be stored in the cache used to filter out entry duplicates.

When the entry duplicates filtering is active, the Union workflow element stores the returned entry DNs in a cache. A cache is specified to a search operation, and when the cache is full, the search operation is aborted. By default, the cache can handle 10000 DNs. When the cache size is set to 0 or is negative, then no limit is enforced.

Optional

10000

bind-option

This parameter that supports the following bind options:

  • bind-first-success: Allows the bind to fall through the list of all eligible partitions (configured in this workflow element) until it reaches a first success.

  • bind-quick-fail: Causes the bind to immediately throw an error if multiple users from different partitions (configured in this workflow element) have the same DN that is used as a bind DN.

    Specify this option if you want the bind to fail for multiple users having the same DN from different configured partitions.

Optional

  • bind-first-success (default)

  • bind-quick-fail

search-first-match

Indicates if a subtree search should stop the processing once an entry is found. A subtree search with the filter (uid=user.1) is likely to target a single entry. However, in some deployment, there can be several entries with uid=user.1 in the various data sources.

To prevent the union workflow element from returning more than one entry with uid=user.1, set this property to true.

Optional

  • true (default value)

  • false

auto-tune-search-option

A parameter that controls whether the Union workflow element has the intelligence to switch to SearchAllCandidates mode. (This parameter is disabled or set to false, by default)

In certain cases, this workflow element has the intelligence to switch to SearchAllCandidates mode, even if it is configured to SearchFirstMatch when the search filter mandates to search in all candidates. For example, the workflow element can switch modes if the search filter contains non-equality components (such as cn=*), if all of the components are objectclass attributes (such as objectclass=*), and so forth.

Mandatory

  • false (default mode): It disables the workflow element's ability to switch modes.

  • true : If specified, then enables the workflow element to switch to SearchAllCandidates mode.

12.3.6.3 Configuration Parameters for Union Partition

The Union Partition is a subtree in the virtual unified DIT of a union workflow element. Learn about the various Union workflow element configuration parameters, their names, descriptions, and functionality.

Property Description Mandatory or Optional Value

allowed-operations

Defines The list of operations that can be executed in this partition.

By default, all the operations are allowed in the partitions.

Optional

  • add: Allows add operation in this partition.

  • bind: Allows bind operation in this partition.

  • compare: Allows compare operation in this partition.

  • delete: Allows delete operation in this partition.

  • extended: Allows extended operation in this partition.

  • modify: Allows modify operation in this partition

  • modifydn: Allows modifyDN operation in this partition.

  • search: Allows search operation in this partition.

black-list-attributes

The list of attributes of DN syntax that must NOT be transformed. The black-list-attributes specifies the set of attributes that must not be transformed. This attribute is mutually exclusive with white-list-attributes, that is only one of them may be used in the configuration entry.

Optional

List off attributes with a DN Syntax

priority

The priority of the partition. The priority of the partition is used to determine the order in which a request is sent to several partitions. The priority is a positive integer - the lower the value, the higher the priority, and 0 is the highest priority a partition can ever have.

Optional

An integer value. Lower value is.0

Default value is 10.

relative-base-dn

The relative part of the partition base DN. The relative base DN is a sequence of RDNs, and is used to build the partition base DN (The partition base DN is the concatenation of the relative base DN and the union base DN).

For example if the relative base DN is set to ou=people, and the union base DN is dc=example,dc=comthen the partition base DN will be ou=People,dc=example,dc=com.

Note:

The partition base DN is the naming context of the partition in the virtual DIT. The default value for the relative base DN is the null suffix (""). This means that the partition base DN is equal to the union base DN.

Optional

A valid DN.

source-base-dn

The base DN for the source DIT. The source DIT is the place from which entries are read (For example, remote LDAP server) to populate the union partition..

The source base DN need not to be equal to the partition base DN. When the source base DN is different than the partition base DN, a DN mapping is performed silently, and all the attributes with a DN syntax are automatically mapped accordingly. If you want to fine tune which attributes should, or should not be mapped, then you must set the white-list-attributes or the black-list-attributes.

Optional

A valid DN.

white-list-attributes

The list of attributes with DN syntax that must be transformed. The white-list-attributes specifies the set of attributes that must be transformed. This attribute is mutually exclusive with black-list-attributes, that is only one of them may be used in the configuration entry.

Note:

If the black-list-attribute property is not specified then, all attributes with a DN syntax are transformed

Optional

List off attributes with a DN Syntax

workflow-element

The partition workflow element. The workflow element to use as a data source to populate the partition.

Mandatory

The DN of any Workflow Element.

Note:

Ensure that theenabled configuration property of the referenced workflow element is set to true .

12.4 Understanding Data Integration Using the Proxy

You can use different methods to retrieve and integrate data from a variety of sources, including databases and directories, to present a unified view of that data.

The following topics describes the different methods:

Note:

For information about configuring data integration, see Configuring Integration Using the Proxy.

12.4.1 Understanding How to Retrieve All Attribute Values from an Active Directory Server

You can retrieve the complete set of values for the attribute from an active directory server by performing multiple search requests, each retrieving a distinct subset.

Retrieving the contents of a multi-valued attribute sometimes result in a large number of returned values. Microsoft Active Directory server limits the maximum number of attribute values that can be retrieved in a single query.

Microsoft Active Directory provides a range retrieval mechanism that allows you to retrieve all the values of a multi-valued attribute. This mechanism permits a client-specified subset of the values to be retrieved in a search request. By performing multiple search requests, each retrieving a distinct subset, the complete set of values for the attribute can be retrieved.

Oracle Unified Directory handles Active Directory range retrieval by providing support for Microsoft Active Directory paging. The main purpose of Microsoft Active Directory paging is to detect if a range option is present among the options of the returned attributes and to retrieve the complete range of attribute values from the Microsoft Active Directory server. This complete set of attribute values is returned, so that the client application does not have to deal with the range option.

Microsoft Active Directory paging is implemented as a workflow element that is relevant only if the leaf of the workflow element chain is connected to an Active Directory server. You can configure the following properties of an Active Directory Paging workflow element:

  • The next workflow element in the chain as this workflow element is not a leaf workflow element

  • An optional list of attributes that can reduce the processing of scanning attributes to detect the range option

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

Note:

For information about how to configure Microsoft Active Directory paging, see Retrieving All Attribute Values from an Active Directory Server.

12.4.2 About Enterprise User Security Databases Integration

You can integrate Oracle Unified Directory and Enterprise User Security to leverage user identities stored in an LDAP-compliant directory service without any additional synchronization.

When integrated with Enterprise User Security, Oracle Unified Directory supports the following:

  • Microsoft Active Directory

  • Novell eDirectory

  • Oracle Unified Directory

  • Oracle Directory Server Enterprise Edition

For more information about Oracle Enterprise User Security, see the Oracle Database Enterprise User Security Administrator's Guide. For detailed instructions on configuring Oracle Unified Directory and Enterprise User Security to work together, see Integrating Oracle Unified Directory with Oracle Enterprise User Security.

12.4.3 Overview of Enabling LDAP Clients to Update User Passwords Stored in Active Directory

The Ad Password workflow element enables Oracle Unified Directory LDAP client applications to update user passwords stored in Microsoft Active Directory and Active Directory Lightweight Directory Services (AD LDS) using the LDAP protocol.

This section includes the following topics:

To configure an Ad Password workflow element, see Updating User Passwords Stored in Active Directory.

12.4.3.1 About Ad Password Workflow Element

Microsoft Active Directory and AD LDS have characteristics and requirements that Oracle Unified Directory LDAP clients cannot always handle using standard LDAP operations.

For example, if a client updates a user password (userPassword attribute) using a standard LDAP modify operation, the update is successful on most LDAP servers. Active Directory will accept this modify operation, but it will not update the user password because of the following requirements:

  • Active Directory stores a user password in the unicodePwd attribute on a user object rather than in the userPassword attribute.

    The syntax for the unicodePwd attribute is an octet-string containing a UNICODE string enclosed in double quotes (").

  • The unicodePwd attribute cannot be added during the creation of a user object. The user object must first be created without the unicodePwd attribute and then the attribute is added on the new object with a modify operation.

  • Only an administrator can reset a user password without knowing the previous password.

  • Active Directory user passwords can be updated only over an SSL connection.

The Ad Password workflow element can handle these specific requirements. It allows existing client applications to update user passwords stored in Active Directory or AD LDS using standard LDAP operations, without requiring the client applications to be re-coded.

For the supported versions of Active Directory and AD LDS, check the Oracle Unified Directory 11g Release 2 (11.1.2.3) Certification Matrix.

12.4.3.2 Understanding Ad Password Workflow Element Functionality

The Ad Password workflow element performs specific functions, depending on the LDAP operation it is processing.

This section includes the following topics:

12.4.3.2.1 Understanding Ad Password Workflow Element Mechanism for ADD Operations

If a secure proxy LDAP workflow element is configured, the Ad Password workflow element handles an ADD operation that contains a userPassword attribute as follows:

  • Maps the userPassword attribute to the unicodePwd attribute (map-userpassword property is set to true).

  • Handles the ADD operation that contains a userPassword attribute in the following order:

    1. Executes an ADD operation on the Active Directory user object without the unicodePwd, useraccountcontrol, and msds-useraccountdisabled attributes. This operation is handled by the workflow element defined by the next-workflow-element property in the Ad Password workflow element.

    2. Executes a MODIFY operation on the user object to create the unicodePwd attribute. This operation is handled by workflow element defined by the secure-proxy-workflow-element property in the Ad Password workflow element.

    3. If the original ADD operation contained a useraccountcontrol or msds-useraccountdisabled attribute, executes a MODIFY operation on the user object. This operation is handled by the workflow element defined by the next-workflow-element property in the Ad Password workflow element.

      The useraccountcontrol and msds-useraccountdisabled attributes cannot be set before the unicodePwd attribute is created in Step 2.

If Step 2 or Step 3 fails either during the bind or the MOD operation, the ADD operation is rolled back (that is, the entry is deleted).

If a secure proxy LDAP workflow element is not configured, the Ad Password workflow element handles an ADD operation that contains a userPassword attribute as follows:

  • Maps userPassword to unicodePwd, if needed (map-userpassword property is set to true).

  • Handles the ADD operation by the workflow element defined by the next-workflow-element property in the Ad Password workflow element. If the next-workflow-element does not use SSL, then Active Directory might refuse the operation.

12.4.3.2.2 Understanding Ad Password Workflow Element Mechanism for MODIFY Operations

If a secure proxy LDAP workflow element is configured, the Ad Password workflow element handles a MODIFY operation that contains a userPassword attribute as follows:

  1. Executes a MODIFY operation on the user object with the user password change. This operation is handled by the workflow element defined by the secure-proxy-workflow-element property in the Ad Password workflow element.

    If this step fails either during the bind or the MOD operation, Oracle Unified Directory returns the MOD result code to the client without trying Step 2.

  2. Executes the MODIFY operation on the object. This operation is handled by the workflow element defined by the next-workflow-element property in the Ad Password workflow element.

If a secure proxy LDAP workflow element is not configured, the Ad Password workflow element handles a MODIFY operation that contains a user password as follows:

  • Maps userPassword to unicodePwd, if needed (map-userpassword property is set to true).

  • Executes a MODIFY operation on the object. This operation is handled by the workflow element defined by the next-workflow-element property in the Ad Password workflow element.

12.4.3.3 About Ad Password Workflow Element Check for an SSL Connection

When SSL is required, the Ad Password workflow element checks that an SSL connection is configured to the remote Active Directory or AD LDS server, as follows:

  • If you configure a secure-proxy-workflow-element, Oracle Unified Directory will check that this workflow element is a proxy LDAP workflow element that is using an LDAP server extension configured to always use SSL (remote-ldap-server-ssl-policy property set to always).

  • If you do not configure a secure-proxy-workflow-element, the next-workflow-element must use an LDAP server extension configured to always use SSL.

If operations on a user password fail because of an incorrect configuration, the Ad Password workflow element returns the error codes it receives from the remote Active Directory or AD LDS server.

12.4.3.4 Considerations for Using the Ad Password Workflow Element

Before you create and configure an Ad Password workflow element, consider your deployment's security and performance requirements using the following use cases:

See Also:

12.4.3.4.1 About All LDAP Operations Over an SSL Connection Configuration

This use case performs all LDAP operations between clients and Active Directory or AD LDS server over an SSL connection.

The advantage of this use case is that all LDAP operations are always performed over a fully secure SSL connection, regardless of how the client connects to the proxy server. A disadvantage is that some LDAP operations performed over an SSL connection can cause performance degradation for your deployment.

Configuration Requirements

This use case requires the following components:

  • An LDAP server extension configured with the remote-ldap-server-ssl-policy property set to always.

  • A secure proxy LDAP workflow element that points to an LDAP server extension as described in the previous item (that is, configured with the remote-ldap-server-ssl-policy option set to always).

  • An Ad Password workflow element configured with the next-workflow-element property pointing to a secure proxy LDAP workflow element.

12.4.3.4.2 About Only LDAP Operations for Password Modifications Over an SSL Connection Configuration

This use case performs operations that are related to password modifications over an SSL connection to Active Directory or AD LDS server. Other LDAP operations are performed over an SSL or non-SSL connection according to the remote-ldap-server-ssl-policy configuration property of the LDAP server extension used by next-workflow-element.

An advantage of this use case is that it forces password modifications to take place over an SSL connection, without requiring all communications to the remote server to use SSL. The other communications can either never use SSL or use SSL only if the client connection is using SSL.

Configuration Requirements

This use case requires the following components:

  • Two LDAP server extensions to communicate with the remote Active Directory or AD LDS server:

    • An LDAP server extension for SSL connections. The remote-ldap-server-ssl-policy property must be set to always.

    • Another LDAP server extension for operations not related to password modifications. The remote-ldap-server-ssl-policy property is set to either never or user (or omitted).

  • Two proxy LDAP workflow elements to communicate with the remote Active Directory or AD LDS server:

    • A secure proxy LDAP workflow element for SSL connections.

    • Another proxy LDAP workflow element for operations not related to passwords.

  • Ad Password workflow element configured with both the secure-proxy-workflow-element and next-workflow-element properties:

    • LDAP operations that modify the user password are handled by the workflow element specified by the secure-proxy-workflow-element property and will take place over an SSL connection.

    • Other LDAP operations not related to password modifications are handled by the workflow element specified by the next-workflow-element.

12.4.3.4.3 About Active Directory Configuration When Attribute Mapping is Not Required

With a specific configuration, Active Directory and AD LDS can handle modifications on the userPassword attribute without requiring the userPassword attribute to be mapped to the unicodePwd attribute.

This Active Directory or AD LDS configuration requires:

  • The domain controller (DC) must be running as Active Directory or AD LDS, and the domain functional level must be Windows 2003 or greater.

  • The fUserPwdSupport character must be set to true in the dSHeuristics attribute.

For more information about this specific configuration, see the following Microsoft document:

http://msdn.microsoft.com/en-us/library/cc223249.aspx

For this configuration, user password attribute mapping is not required. To control this mapping, the Ad Password workflow element provides the map-userpassword property:

  • true (default) enables mapping. The userPassword attribute is automatically mapped to unicodePwd. LDAP ADD and MODIFY operations are then performed on unicodePwd instead of userPassword.

  • false disables mapping. LDAP ADD and MODIFY operations are performed on userPassword.

12.4.4 Understanding Pass-Through Authentication

Pass-through authentication (PTA) is a mechanism where one directory server consults another directory server to authenticate bind requests. A typical scenario for pass-through authentication involves passing authentication through to Active Directory for users coming from Oracle Unified Directory.

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

The following topics describe the use and operation of pass-through authentication:

Note:

For information about configuring pass-through authentication, see Overview of Configuring Pass-Through Authentication.

12.4.4.1 Overview of the Pass-Through Authentication Mechanism

You use the pass-through authentication mechanism when the client attempts to bind to the directory server and the user credentials for authenticating are not stored locally, but instead in another remote directory server known as the authentication (Auth) server. The directory server then redirects the bind operation to the authentication server to verify the credentials. The credential here refers to the userpassword attribute. The Auth server that stores the user credentials can be Oracle Unified Directory, Microsoft Active Directory, or an LDAP V3 compliant directory server.

Exactly how Oracle Unified Directory redirects the bind depends on how the user entry in user server maps to the corresponding user entry in the authentication server. Oracle Unified Directory supports one-to-one mapping between the user entry and the authentication entry.

To gain a better understanding of the pass-through authentication mechanism, consider the example depicted in Figure 12-12.

Figure 12-12 Pass-Through Authentication Mechanism

Description of Figure 12-12 follows
Description of "Figure 12-12 Pass-Through Authentication Mechanism"

Let us consider two servers, say server A and server B and a user entry cn=myuser stored on server B. Now, if a user attempts to access server A to perform any operation it has to first bind to server A with its credentials for authentication. However, the credentials are not present on server A, therefore the bind to server A would normally fail. But, using the pass-through authentication mechanism, server A can verify the credential by directing the bind request to server B. After the credentials are validated using server B, and the bind is successful then server A returns success for the bind operation.

The Server A in this example acts as the user directory server or the pass-through authentication directory server. This is because it is the server that passes the bind request to another directory server. The authentication directory server B, acts as the authenticating directory, the server that contains the entry and verifies the bind credentials of the requesting client.

12.4.4.2 Understanding the Pass-Through Authentication Configuration Model

Oracle Unified Directory implements pass-through authentication using pass-through authentication workflow element that allows you to administer your user and authentication directories on separate instances of directory server.

The user provider is a workflow element that contains the user entries, which is to say all attributes except the password of the user. On the other hand, the authentication provider is the workflow element that contains the user password.

Note:

Oracle Unified Directory provides support for local back end or proxy for both user provider workflow element and authentication provider workflow element. However, Kerberos is supported for authentication provider workflow element only.

Figure 12-13 illustrates a pass-through authentication configuration model.

Figure 12-13 Pass-Through Authentication Configuration Model

Description of Figure 12-13 follows
Description of "Figure 12-13 Pass-Through Authentication Configuration Model"
12.4.4.3 Understanding the Pass-Through Authentication Configuration Parameters

Table 12-1 describes the configuration parameters used in the pass-through authentication configuration model described in Understanding the Pass-Through Authentication Configuration Model.

For more information about configuring pass-through authentication using dsconfig command, see Overview of Configuring Pass-Through Authentication.

For more information about configuring pass-through authentication using OUDSM, see Creating a Workflow Element.

Table 12-1 Configuration Parameters Used in Pass-Through Authentication Process

Parameter Description

user-provider-workflow-element

User Provider Workflow Element

This parameter defines the workflow element that contains the user entries. This workflow element is used for all the operations except BIND.

This is a mandatory parameter.

auth-provider-workflow-element

Authentication Provider Workflow Element

This parameter defines the workflow element that contains the authentication entry and verifies the bind credentials of the requesting client. This workflow element is used for BIND and MODIFY operations on the userpassword attribute.

This is a mandatory parameter.

save-password-on-successful-bind

This parameter allows you to enable or disable the password-copy feature. If this parameter is set to true, and the BIND on the authentication provider workflow element succeeds then a copy of the password is saved in the user provider workflow element. The copy is a MODIFY operation applied on the DN used for the bind, replacing the value userpassword with the value of the password used for the bind.

This is an optional parameter. The default value is false.

password-attribute

This parameter defines the attribute in which the password value is copied in the user entry when the password-copy feature is enabled. After the password is saved, it can be copied in the userpassword attribute or in another attribute in the user provider workflow element.

This is an optional parameter. The default value is userpassword.

pta-suffix

This parameter defines the virtual DN that is exposed by the pass-through authentication workflow element.

This is an optional parameter. By default, this parameter is not set and implies that there is no DN mapping.

user-suffix

This parameter defines the actual suffix that contains the user entries on the user provider workflow element.

This is an optional parameter. By default, this parameter is not set and implies that the DN is the same as the pta-suffix parameter.

auth-suffix

This parameter defines the actual suffix that contains the authentication entries on the authentication provider workflow element.

This is an optional parameter. By default, this parameter is not set and implies that the DN is the same as the pta-suffix parameter.

pta-join-rule

This parameter defines the mapping between an authentication entry and a user entry.

This is an optional parameter. By default, this parameter is not set and implies that the rule is auth.dn=user.dn.

12.4.4.4 Overview of Pass-Through Authentication Implementation for Different Servers

If your user entries are stored on a Kerberos server, then you must configure a Kerberos workflow element.

This section contains the following topics:

See Configuring Pass-Through Authentication for Different Servers for more information.

12.4.4.4.1 Understanding Pass-Through Authentication Workflow Element Features

The following is a list of some pass-through authentication workflow element capabilities:

  • Allows you to route requests to a specific workflow element depending on the request type. For instance, bind requests are routed to authentication workflow element. When you apply MODIFY on any attribute except userpassword it is routed to the user workflow element. Applying MODIFY on the userpassword attribute is routed to the authentication workflow element (and also to the user workflow element if password-copy is enabled). All other requests, such as ADD, DELETE, RENAME, COMPARE, and SEARCH are routed to the user workflow element.

  • Support for Kerberos workflow element as an authentication workflow element. When the authentication workflow element is a Kerberos workflow element, Oracle Unified Directory forwards the authentication request to a Kerberos server, and the authentication is performed using Kerberos protocol instead of LDAP bind.

  • Simplifies migration from an external LDAP server containing user credentials to Oracle Unified Directory. During the migration phase, the pass-through authentication workflow element copies the user password from the external LDAP server to Oracle Unified Directory on successful bind. This feature is called as password-copy. For instance, when a user successfully authenticates, the bind is routed to the authentication workflow element, which is the external LDAP server. The pass-through authentication workflow element then stores the password used for this bind operation in the user workflow element. This migration phase populates the user password attribute of all the users that initiated contact during the migration phase.

  • Support cases where the entry on the authentication workflow element is linked to the entry on the user workflow element by a join rule and an authentication suffix. This join rule can be a DN=DN mapping or a simple join rule with the following format: 

    auth.<Attribute1>=user.<Attribute2>

    For more information about join rules, see Overview of Join Rules.

    The mapping between the user entry and the authentication entry must be a one-to-one mapping, which implies that each entry in the user provider corresponds with one entry in the authentication provider.

  • Support for DN mapping, for instance allows you to publish entries below dc=pta,dc=com whereas the user workflow element suffix is dc=user,dc=com.

  • Support for password modification.

  • Support for all kinds of workflow element for the user workflow element, local or remote.

12.4.4.4.2 Considerations for Using Pass-Through Workflow Element

When using the pass-through authentication workflow element, you must keep the following in mind:

  • The authentication workflow element handles only bind requests.

  • The user provider workflow element is used for all other operations, such as ADD, DELETE, RENAME, COMPARE, and SEARCH.

  • The MODIFY operation depends on the save-password-on-successful-bind parameter. This parameter saves the password if needed in the user workflow element when pass-through authentication workflow element binds successfully with the authentication workflow element.

    If save-password-on-successful-bind is enabled, then userpassword parameter is modified on both participants.

    If save-password-on-successful-bind is disabled, then the userpassword is modified on the authentication participant only.

  • If you define the user-suffix or auth-suffix parameter, then you must define the pta-suffix. Both parameters apply to DN renaming between the user or authentication participant and the pass-through authentication participant.

  • If a join rule is defined, and the authentication and user entries do not necessarily have the same DN, then you must define the auth-suffix.

  • Note, if user-suffix is not defined, then the workflow element assumes that the user-suffix=pta-suffix. The same applies if the auth-suffix not defined. Here, again the workflow element assumes that the auth-suffix=pta-suffix.

12.4.4.4.3 Handling LDAP Operations Using Pass-Through Authentication Workflow Element

Oracle Unified Directory supports the following LDAP operations using pass-through authentication workflow element:

Operation Description

ADD

All ADD operations processed through the pass-through authentication workflow element are sent to the user provider workflow element.

  • If the save-password-on-successful-bind parameter is set to true, then the userpassword attribute is also stored in the user-provider workflow element.

  • If the feature is disabled, then the userpassword attribute is not stored in the user-provider workflow element.

BIND

The BIND operation is routed to the authentication-provider workflow element.

  • If the BIND is successful and the save-password-on-successful-bind parameter is enabled, the pass-through authentication workflow element also tries to attempt a BIND on the user-provider workflow element to check if there is a local copy of the password.

  • If the BIND fails, then the userpassword attribute is copied to the user-provider workflow element.

COMPARE

The COMPARE operation is routed to the user-provider workflow element. The COMPARE operation that is applied to the userpassword attribute is routed to the user-provider workflow element, which may not contain the attribute unless the save-password-on-successful-bind parameter is enabled.

DELETE

The DELETE operation is routed to the user-provider workflow element only. The entry on the authentication server is not deleted.

MODIFY

For all attributes except userpassword, the modifications are performed on the user-provider workflow element. For the userpassword attribute:

  • If save-password-on-successful-bind parameter is enabled, then the password is modified on both the user-provider workflow element and the authentication-provider workflow element.

  • If save-password-on-successful-bind parameter is disabled, the password is modified on the authentication-provider workflow element only.

  • If the authentication provider is a Kerberos workflow element, then the modify password operations fails.

MODIFY_DN

The pass-through authentication workflow element processes MODIFY_DN on the user-provider workflow element only and does not modify the entry on the authentication-provider workflow element.

SEARCH

The SEARCH operations are routed to the user-provider workflow element only. This in turn implies, that a SEARCH operation that submits a request for the userpassword attribute might not return any value unless there is a copy in the user-provider workflow element.

12.4.4.5 Understanding Implementation of Pass-Through Authentication for a Kerberos Server

If your user entries are stored on a Kerberos server, then you must configure a Kerberos workflow element. See Configuring Pass-Through Authentication for a Kerberos Server for more information.

12.4.5 Understanding Oracle Unified Directory Plug-Ins

Oracle Unified Directory provides a plug-in API that enables you to extend existing directory server functionality. A plug-in is similar to a workflow element and you can insert a plug-in into any Oracle Unified Directory workflow element tree.

You may want to develop your own plug-ins when you have a particular directory server requirement and Oracle Unified Directory does not provide the necessary functionality to accommodate that requirement.

For more information about Oracle Unified Directory plug-ins, see "Understanding Basic Oracle Unified Directory Plug-in Concepts" in the Oracle Fusion Middleware Developing Plug-Ins for Oracle Unified Directory.

12.5 Understanding Virtualization

You can view and retrieve data from virtual directories and data sources using different features.

The following sections describe how different Oracle Unified Directory features enable you to view and retrieve data from virtual directories and data sources:

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

12.5.1 Using Entries from Multiple Directories

You can understand about the Join workflow element, which presents a virtual directory view of your repositories and routes data to and from those repositories from the following sections.

This section covers the following topics:

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

12.5.1.1 Understanding the Join Workflow Element

For most enterprises, user identity information such as user profiles, access data, and authorization data for a single entry is scattered across heterogeneous data sources at multiple locations. For example, employee information is stored in HR databases or in Microsoft Active Directories, customer and partner data in CRM databases, and additional LDAP directories. Companies require aggregated user data from various data sources in real time. As a consequence, application-specific directories proliferate, copying and synchronizing identity data, which leads to high administration and maintenance costs, inconsistent identity data, and compliance issues.

Oracle Unified Directory provides a directory service solution that addresses these challenges. Oracle Unified Directory supports the Join workflow element that presents a virtual directory view of the repositories and then routes data to and from the repositories.

Oracle Unified Directory enables you to define workflow elements, such as the Proxy LDAP workflow element, to connect to its underlying data repositories. The Join workflow element enables you to combine data from different workflow elements, as needed, to present a customized directory tree.

The Join workflow element is dynamic and does not require synchronization between its data sources. It consolidates identity data without moving data from its native locations, and reuses identity data without copying. These capabilities lead to ease of deployment, diminished costs, simplified identity infrastructure, and a high return on investment by eliminating the need to constantly adapt the applications from changes in the identity stores.

Note:

Be aware that directory virtualization is not running a directory server in a virtualized environment.

When data corresponding to a single entry is spread across multiple data sources, this workflow element combines those different data sources into one unified LDAP view, which is similar to a relational database's table join. Join workflow element does not connect to the underlying data repository. Instead, it builds on top of one or more proxy sources or local back ends to assemble its data as needed. Think of the Join workflow element as joining two or more data repositories by defining Join relationships, known as Joiners, between workflow elements. You can configure as many workflow elements as needed.

Note:

Do not confuse Join with Distribution.

  • Use Distribution when some entries are on server A and others on server B. A given entry is stored inside a single server, either A or B, with all its attributes.

  • Use Join when a part of the entry (such as some attributes) is stored on server A and another part is stored on server B.

For more information about the Distribution workflow element, see Configuring a Distribution Deployment Using the dsconfig Command.

12.5.1.1.1 About Join Workflow Element Features

Following are key features of the Join workflow element:

12.5.1.1.2 Understanding the Join Workflow Element Configuration Model

Figure 12-14 illustrates the configuration model for the Join workflow element and Join participants using Join rules.

A participant is a workflow element that contributes information to the Join workflow element to form a combined joined entry. Join rules determine how an entry from one participant relates to an entry from another participant.

Figure 12-14 Join Workflow Element Configuration Model

Description of Figure 12-14 follows
Description of "Figure 12-14 Join Workflow Element Configuration Model"

Oracle Unified Directory treats all the participating elements equally; however, you must configure one participant as primary. You are not required to define a Join rule for a primary participant. In this figure, P1 is the primary participant and all other participants P2 though P8, are secondary participants.

Each secondary participant has a Join rule and has a Joiner type, which defines its relationship with another participant. For example, in case of P2, the Join rule P2.cn=P1.cn defines its relationship with P1 and if the Joiner type configured in P2 is many-to-one, then it implies that the relationship from P1 through P2 is one-to-many.

Participants P2, P8, and P5 are directly related to the primary participant P1, while the other secondary participants are indirectly related to the primary participant.

Note:

For more information about participants, Join rules, and Joiner types, see the following:

12.5.1.2 Understanding Join Participants

A Join participant is a workflow element that contributes some information to the Join workflow element to form a combined joined entry.

A Join workflow element can have one or more participating data sources, with each exposed through a workflow element. Participating workflow elements include:

  • Distribution workflow element

  • Proxy LDAP workflow element

  • Local Backend workflow element

  • Load Balancing workflow element

  • Another Join workflow element

For example, for each directory, you must create a Proxy LDAP workflow element that is associated with a directory to retrieve information from that directory. Afterward, you formulate these workflow elements as participants of a Join workflow element.

Figure 12-15 depicts the relationship between a Join workflow element and the participating workflow elements.

Figure 12-15 Join Workflow Element and Join Participants

Description of Figure 12-15 follows
Description of "Figure 12-15 Join Workflow Element and Join Participants"

A Join workflow element has only one primary participant, whose Directory Information Tree (DIT) structure is exposed by default, and can have one or more secondary participants. You determine which participant is primary.

You use the primary participant to create and search the directory tree entries. Entries must exist in the primary participant to be returned from a Join workflow element.

The Join workflow element takes each entry found in the primary participant and joins it with entries in other participants, based on the defined Join rule. You can also configure the Join workflow element to expose entries in the primary participant and entries that reside only in the secondary participants. For information about Join Rules, see Overview of Join Rules.

The Join workflow element and each participant must have an associated suffix (a DN).

  • A Join workflow element DN is the virtual DN that is exposed through the workflow associated with that Join workflow element. You can configure the Join workflow element to restrict the view to only the Directory Information Tree that is of interest to the client.

  • Ideally, a participant DN is the back-end naming context that is exposed through that participating workflow element or a descendant DN of that workflow element.

12.5.1.3 Overview of Join Rules
12.5.1.3.1 Understanding Join Rules

Join rules determine how an entry from one participant relates to an entry from another participant. Defining Join rules enables the Join workflow element to query secondary participants during LDAP operations.

Note:

  • A Join rule always specifies the relationship between two, and only two, participants.

  • You define Join rules only for secondary participants and not for a primary participant.

The Join workflow element forms a search filter to search each secondary participant based on the Join rule defined for that secondary participant.

When you configure a Join workflow element, you must configure a Join rule for each secondary participant that specifies a relationship between entries in one participant with entries in the other participant. Also, the Join rule specified in at least one of the secondary participants must involve the primary participant, so that the Join workflow element can traverse the entire relationship tree starting from the primary participant.

Join rules identify the attributes of an entry from one participant to search another participant for obtaining the matching entries. These matching entries are then joined with the original entry to form the joined entry. When a matching value is found in the destination view, a join between the two entries is created.

The Join workflow element adds an attribute value, joinedentrydn, for each entry retrieved from a participating element. This value indicates which entries from secondary participants were used to form the consolidated entry. You can decide whether to configure the Join workflow element to populate this attribute, which might be useful when troubleshooting Join issues.

Oracle Unified Directory supports the following Join rule types:

  • LDAP filter Join rules

  • DN Join rules

Join rules follow LDAP filter syntax, which enables you to create complex Join rules using AND and OR. For example: 

(&(P1.userId = P2.uid)(|(P1.deptNumber = P2.department)(P1.empNum = P2.empId)))

Note:

In a Shadow Join relationship, the Join rule must use the same attribute in both the primary and the shadow participant. For example, p1.cn = p2.cn.

For more information, see Shadow Joiner Type.

Following are examples of valid Join rules:

  • p3.uid=p2.uid

  • (&(P5.title=Primary.title)(Primary.cn=P5.sn))

  • P5.dn = P7.dn

  • P8.member = Primary.dn

  • Primary.dn = P2.uniquemember

Note:

the order in which you define the Join rule does not matter. For example, P1.cn=P2.commonname is the same as P2.commonname=P1.cn.

12.5.1.3.2 Understanding Attribute-Based Join Rules

Attribute-based Join rules define a Join relationship between two participants based on the common attribute values present in the matching entries from two participants.

For example, consider the Join rule p1.uid=p2.username, where p1 and p2 are two Join participants. This Join rule indicates that for an entry in p1, a corresponding matching entry from p2 is retrieved and joined with the entry from p1, if the uid attribute value of an entry from p1 matches the username attribute value of an entry from p2. If uid is a multi-valued attribute in p1, then the corresponding entry in p2 must match at least one of the values of p1. For instance, if the entry in p1 contains uid=user.12 and uid=user.34, then the entry from p2 must contain either uid=user.12 or uid=user.34.

12.5.1.3.3 Understanding DN Join Rules

In some situations, the participating data sources do not have any attribute values in common except the entry DN. In these cases, you can configure a Join rule involving Entry DN.

A DN Join rule uses DN syntax and can take one of the following forms:

  • The entry DN in one participant is constructed from an attribute in another participant. The DN must not contain the baseDN of the secondary participant, which makes it a relative DN. For example, you can configure the following DN join rule, which stipulates that the entry DNs in participant P2 must include the cn from participant P1, plus the ou=people suffix.

    P2.dn = "cn={P1.cn},ou=people"

  • The entry DN in one participant matches an attribute in another participant. For example, you can configure this rule using the following syntax

    P8.member = P7.dn

    The preceding DN Join rule stipulates that the member attribute value in P8 should be used for locating the matching entries from P7.

  • The entry DN in one participant is same as the entry DN in another participant. For example, you can configure this rule using the following syntax:

    P2.dn = P3.dn

    This Join rule stipulates that an entry DN in P2 must match an entry DN in P3 to form a joined entry. In this case, the Join rule looks for matching entries in portions of the DNs below the participant suffixes, although the full DNs may differ. For example, if participant P2 has a dc=primary suffix and participant P3 has a dc=secondary suffix, then the Join rule implies that the trees below the suffixes are identical and it associates the "uid=user.1,cn=users,dc=secondary" entry with "uid=user.1,cn=users,dc=primary."

12.5.1.4 Overview of Join Policies

The following sections describe the different Join policies that govern joins between primary and secondary participants:

12.5.1.4.1 Understanding Join Policies

This section describes the different Join policies that govern joins between primary and secondary participants. Specifically, these policies determine which entries to return, including entries from only the primary participant, only from the secondary participant, or from both primary and secondary participants.

Oracle Unified Directory supports the following Join policy types:

  • Standard Join Policy Type:

    If you specify the Standard Join policy type, then Oracle Unified Directory returns all entries in the primary participant that satisfy the search filter after joining the corresponding entries in the secondary participants.

  • Left Outer Join Policy Type:

    If you specify the Left Outer Join policy type, then Oracle Unified Directory returns all entries in the primary participant after joining them with corresponding entries in secondary participants (by using a Standard Join), and then returns entries from the secondary participants that satisfy the join criteria and have a corresponding match in the primary participant. This process is equivalent to a Left Outer Join in database terminology.

    If you are joining entries from a secondary participant to a primary participant, then the join relationship is reversed. For example, a one-to-many join from the primary participant to a secondary participant becomes a many-to-one join, which is the same as a one-to-one join, from a secondary participant to the primary participant. Similarly a many-to-one join from primary to secondary becomes a one-to-many join from secondary to primary.

  • Full Outer Join Policy Type:

    If you specify the Full Outer Join policy type, then Oracle Unified Directory returns all the entries in the primary participant after joining them with corresponding entries in secondary participants (by using a Standard Join), and then returns entries from the secondary participants that satisfy the join criteria and have a corresponding match in the primary participant (by using a Left Outer Join), and then returns entries from the secondary participants that satisfy the search filter, but do not have a matching entry in the primary participant. This process is equivalent to a Left Outer Join + Right Outer Join in database terminology.

    If you are joining entries from a secondary participant to a primary participant, then the join relationship is reversed. For example, a one-to-many join from the primary participant to a secondary participant becomes a many-to-one join, which is the same as a one-to-one join, from a secondary participant to the primary participant. Similarly a many-to-one join from primary to secondary becomes a one-to-many join from secondary to primary. For a Full Outer join, Oracle Unified Directory ignores the join condition for entries from secondary participants because it cannot compute the reverse of the join condition.

Note:

If you do not specify a particular Join type, then Oracle Unified Directory performs the Standard Join by default.

12.5.1.4.2 Example of Using a Join Policy

The following table illustrates how each of the Join Policies work. For this example, assume the following data resides in the primary participant and a secondary participant:

  • The primary participant namespace is dc=internal, dc=com

  • The secondary participant namespace is dc=external, dc=com

  • The Join workflow element suffix is dc=example,dc=com

Table 12-2 How Join Policies Work

Data in Primary Participant Data in Secondary Participant 
dn: cn=Ronald, dc=internal,dc=com
objectclass: inetorgperson
cn: Ronald
sn: Anne
givenname: Anne Ronald
telephonenumber: 54300
 
dn: cn=Ronald, dc=external,dc=com
objectclass: inetorgperson
cn: Ronald
sn: Anne
title: Manager
 
dn: cn=Sam, dc=internal,dc=com
objectclass: inetorgperson
cn: Sam
sn: Ketty
manager:  cn=Ronald, dc=internal,dc=com
telephonenumber: 54301
 
dn: cn=Sam, dc=external,dc=com
objectclass: inetorgperson
cn: Sam
sn: Ketty
title: SMTS
 
dn: cn=Richard,dc=internal,dc=com
objectclass: inetorgperson
cn: Richard
sn: Rod	
title: Trainee
manager: cn=Ronald, dc=external,dc=com
telephonenumber: 54303
description: Trainee for dept 543
departmentNumber: 543
 
dn: cn=Richard,dc=external,dc=com
objectclass: inetorgperson
cn: Richard
sn: Rod		
title: Trainee
 
dn: cn=William,dc=internal,dc=com
objectclass: inetorgperson
cn: William	
sn: Tent
description: User with no title
 
dn: cn=Mike,dc=external,dc=com
objectclass: inetorgperson
cn: Mike	
sn: Ret
title: MTS - dept_sec
12.5.1.5 Understanding Supported Joiner Types

A Joiner type defines the Join relationship between two participants. A Join relationship defines the way two Join participants are connected. In addition, a Join relationship between two participants is directed and defines the way a start participant is connected to the end participant. These Joiner types work for any kind of Join rule defined, complex or simple.

Note:

When a Join relationship from P1 to P2 with many-to-one Joiner type is configured, then internally Join workflow element implicitly creates a reverse relationship from P2 to P1 with one-to-many Joiner type and vice-versa. For a one-to-one Joiner and a shadow Joiner, the reverse relationship also contains the same Joiner type as that of the original relationship configured.

The following is a description of the supported Joiner types, including:

12.5.1.5.1 One-to-One Joiner Type

The one-to-one Joiner, or simple join, defines a one-to-one relationship between the entries in two participants. In a one-to-one Joiner type, each entry in the start participant corresponds with one entry in the end participant of this relationship. If more than one matching entry exists in the end participant, then the Join workflow element uses the first returned entry from the end participant for the Join.

You can specify a more complex Join criterion involving a combination of AND and OR conditions using the LDAP filter syntax for the Join criteria. For example: 

( & (P1.userId = P2.uid) ( | (P1.deptNumber = P2.department) (P1.empNum = P2.empId) ) )

In the preceding scenario, the search filter used for the secondary participant is coined based on the complex Join criteria configured. If the entry from primary participant does not have all the primary attributes specified in the Join rule, then the Join is not formed.

Figure 12-16 shows a a high-level example of a one-to-one Joiner used for authentication.

Figure 12-16 Sample One-to-One Joiner Type for Authentication

Description of Figure 12-16 follows
Description of "Figure 12-16 Sample One-to-One Joiner Type for Authentication"
12.5.1.5.2 One-To-Many Joiner Type

The one-to-many Joiner type defines a one-to-many relationship between two participants. Similar to a one-to-one Join relationship, the one-to-many Joiner locates entries in the end participant by comparing attributes; however, if an entry in the start participant corresponds with more than one entry in the end participant, this Joiner type consolidates all of the matching entries into one virtual joined entry.

The one-to-many Join is useful if you must consolidate multiple role objects or identities into one virtual entry.

Figure 12-17 depicts a scenario where a policy server makes policy decisions about an individual. For integration purposes, the policy server prefers to see a single entry with the rights of the user exposed as a privilege attribute, which allows the policy server to test rights assertions with queries such as: 

ldapsearch -b "uid=e027451,ou=People,o=LargeCo" -s base "(priv=XYZ Mgr)"

Figure 12-17 One-To-Many Joiner Type

Description of Figure 12-17 follows
Description of "Figure 12-17 One-To-Many Joiner Type"

The one-to-many Joiner is used to match one or more privileges to a user, based on a profile attribute in their main ou=People entry. The one-to-many Joiner looks for all privileges with the same profile value as in the entry and merges them with the entry. A second stage Join uses the one-to-one so that the Oracle Directory Server Enterprise Edition (ODSEE) combined profile is used with the user's Active Directory credentials.

12.5.1.5.3 Many-To-One Joiner Type

The many-to-one Join relationship defines a many-to-one relationship between two participants, where multiple entries in the start participant have a corresponding single entry in the end participant. It is the inverse of one-to-many Joiner type.

For example, assume the primary participant contains a list of employee information and the secondary participant contains a list of department information. If multiple employees belong to one department, then a single department number in the secondary participant might apply to more than one employee in the primary participant.

However, if you delete an employee from the primary participant, you do not want to delete that employee's department number from the secondary participant. You can prevent this "cascading delete," by configuring a many-to-one relationship in the secondary participant. This relationship means that deleting an entry in the primary participant does not result in the deletion of the shared entry in the secondary participant.

12.5.1.5.4 Shadow Joiner Type

You sometimes need to store entries in a source, such as an LDAP store or a Database store, that requires a schema extension, but a schema extension is not possible either for business or technical reasons. The Shadow Joiner allows you to store the extended attributes in another store, such as Local Backend workflow element.

The Shadow Join relationship maintains the same structure of the entry in the primary participant, but stores additional attributes by creating shadow entries using a separate source. Using the Shadow Join relationship, applications can use the enterprise directory and also store application-specific attributes in the shadow directory such as Local Backend workflow element. The application believes it is communicating with a directory that stores all attributes, but Oracle Unified Directory silently stores application-specific data in an alternate shadow directory.

The Shadow Joiner encodes all primary participant DN's into a hash that is used to locate the matching entry in the shadow participant. If the Join workflow element fails to locate a corresponding record in the shadow participant, then it automatically creates a new one, storing the designated attributes in the shadow participant. The Shadow Joiner type operates transparently to the application, taking care of creating and renaming entries synchronized with that of the primary workflow element.

The Shadow Joiner supports all LDAP operations. When an LDAP modify operation occurs, the Shadow Join examines the parameters identified by the shadow participant's storable attributes to see if any of those attributes should be stored in the secondary participant. If any of these attributes exist, then the Shadow Join attempts to locate the local entry using the hash of the primary entry.

  • If the Shadow Join locates the local entry, then it performs the appropriate LDAP modify operation on that entry.

  • If Shadow Join does not find a local entry, it attempts a secondary search. The Shadow Join searches using a primary key, in case the primary DN changed.

    If the local entry is still not found, the Shadow Join automatically creates a new entry.

Note:

For Shadow Joiner, the Join rule should involve the same attribute in both primary and shadow participant. For example, p1.cn = p2.cn.

You must ensure replication is configured for shadow back end to achieve high availability.

Figure 12-18 shows a firewall, for example CheckPoint, configured to connect to an Oracle Unified Directory. The Oracle Unified Directory uses Local Backend Database to maintain the firewall schema, allowing integration of the firewall into the corporate enterprise directory without requiring that the corporate enterprise directory schema be extended with application-specific data. Instead, by storing it in Oracle Unified Directory Local Backend database, the application-specific data can be managed by the team responsible for the firewall management.

Figure 12-18 Example Shadow Join Used for Storing Application-Specific Data Locally

Description of Figure 12-18 follows
Description of "Figure 12-18 Example Shadow Join Used for Storing Application-Specific Data Locally"
12.5.1.6 Understanding the Join Condition

Oracle Unified Directory enables you to define a filter condition for a Join rule, where only those entries that satisfy the specified condition are considered for the Join. All entries that do not satisfy the condition are returned, as is, without a Join.

You can configure a join filter condition with any of the Joiner types described in this chapter. See Understanding Supported Joiner Types for a description of the different Joiner types.

Oracle Unified Directory always evaluates the Join condition with respect to the participant in which it is defined. In most situations, it is useful to define this Join condition only in the primary participant and not in other participants.

You specify a Join condition in the LDAP filter syntax, and you can define a Join condition using any complex filter using OR and AND. For example: 

(&(employeenumber=101)(sn=Smith))

Oracle Unified Directory always evaluates the Join condition based on the participant in which it is defined. In the following example, Oracle Unified Directory considers only the users in P2 whose sn is Smith and departmentNumber is 101 for a join with P3, based on the UserPrincipleName attribute. So, if you defined this configuration for P2, then it is associated with participant P2. 

ds-cfg-join-criteria: P2.uid = P3.UserPrincipleName
ds-cfg-join-condition: (&(departmentNumber=101)(sn=Smith))
12.5.1.7 About Virtual Attributes Creation

You can create virtual attributes based on the physical attributes stored in multiple participants of a Join workflow element. Because an attribute can be obtained from more than one participant, variables that define the attribute content must be fully qualified. That is, the source attribute value must include the name of the participant from which the attribute is taken.

For example, the following parameter creates a "mail" attribute from existing attributes in P1 and P2. This mail attribute is specified in the ds-cfg-create-virtual-attribute configuration parameter of the Join workflow element. 

ds-cfg-create-virtual-attribute: mail =
 {P1.firstName}.{P2.lastName}@{P1.domainName}

In this case, the firstName and domainName attributes are taken from the P1 participant, and the lastName attribute is taken from P2.

The Join workflow element supports creation of virtual attributes based on individual attribute values from each participant. It also supports the simple concatenation or literal/attribute value assignment.

  • department = "ST"

  • empid = P4.uid

  • memberof = P8.dn

  • mail = P3.CN + "." + P2.sn + "@oracle.com";

12.5.1.8 Overview of Attribute Flow Settings

The following topics give an overview of the attribute flow settings, explains the working with retrievable, non-retrievable, storable and non-storable attribute settings:

12.5.1.8.1 Understanding Attribute Flow Settings

Each participating data source has the privilege to specify which attributes can be retrieved from it and which attributes can be stored in it. You can configure this privilege by specifying the following attribute flow settings for each participating workflow element:

  • retrievable-attribute and non-retrievable-attribute

  • storable-attribute and non-storable-attribute

Specifically, these settings control how attributes flow into and out of a Join participant. They also enhance security by preventing information from being requested by, or returned to, an unauthorized client. In addition, for Join workflow elements, the attribute flow settings control which attributes flow to which participant because multiple Join participants can contribute to the same virtual joined entry.

Note:

Unlike access controls, the attribute flow settings provide silent enforcement, which means they filter the request without returning an error to the client. In a high security environment, this silent enforcement prevents the client from knowing whether they are even allowed to see a particular attribute.

12.5.1.8.2 About Retrievable and Non-Retrievable Attribute Settings

When configuring a Join participant, both the retrievable-attribute and non-retrievable-attribute lists are empty by default, which means all attributes are retrievable. However, you can specify a list of attributes that the Join participant can or cannot retrieve as follows:

  • Use the retrievable-attribute setting to specify a list of attributes that the Join participant can retrieve from the target directory.

    This setting contributes to server performance and, in some cases, security because you can only retrieve the specified attributes from a proxied server during SEARCH and COMPARE operations.

    In addition, you can use the retrievable-attribute setting to control attribute flow when using the Join workflow element. Because the Join workflow element Joins entries from multiple participants, you must configure the retrievable-attribute setting on each participant in the Join workflow element to restrict the flow of attributes from the participants in the Join view.

  • Use the non-retrievable-attribute setting to specify a list of attributes that the Join participant cannot retrieve from the target directory.

Specifying a list of retrievable attributes indicates that only specific attributes may be requested from the proxied directory. An empty retrievable-attribute list indicates that all attributes are retrievable — unless you specify a list of non-retrievable attributes.

For example, you can retrieve attribute A1 in the following circumstances:

  • If both the retrievable-attribute and the non-retrievable-attribute lists are empty.

  • If the retrievable-attribute list is empty, and the non-retrievable-attribute list does not contain A1.

  • If the retrievable-attribute list contains A1, and the non-retrievable-attribute list does not contain A1.

12.5.1.8.3 About Storable and Non-Storable Attribute Settings

When configuring a Join participant, both the storable-attribute and non-storable-attribute lists are empty by default, which means all attributes are storable. However, you can specify a list of attributes that the Join participant can or cannot store as follows:

  • Use the storable-attribute setting to specify a list of attributes that the Join participant can store on the target directory.

    This setting contributes to server performance and, in some cases, security because only the specified attributes and their values are sent to the proxied server for ADD and MODIFY operations.

    In addition, you can use the storable-attribute setting to control attribute flow when using the Join workflow element. Because the Join workflow element Joins entries from multiple participants, you must configure the storable-attribute settings on each participant in the Join view to restrict the flow of attributes from participants in the Join view.

  • Use the non-storable-attribute setting to specify a list of attributes that the Join participant cannot store on the target directory.

Specifying a list of attributes indicates that only specific attributes can go to the participating workflow element. An empty storable-attribute list indicates that all attributes are storable — unless you specify a list of non-storable-attributes.

For example, you can store an attribute in the following circumstances:

  • If both the storable-attribute and non-storable-attribute lists are empty.

  • If the storable-attribute list is empty, but the non-storable-attribute list does not contain that attribute.

  • If the storable-attribute list contains the attribute, but the non-storable-attribute list does not contain that attribute.

12.5.1.9 About Bind Operations

The Join workflow element supports user authentication for all participants. The Join workflow element provides a bind fall-through feature that allows you to try password validation against more than one data source. You must authenticate users against more than one data source because user identities might exist in multiple directories and passwords might be stored in any of the data sources.

To use the bind feature, you must configure the bind as an enabled operation in that participant. Use the --set participant-bind-priority configuration parameter to assign a bind priority to each participant in the Join workflow element, which determines the participant's priority in processing the bind.

Each participant is assigned a bind priority and the bind falls through all of the bind participants in the specified order until a successful bind is achieved. A bind failure is returned only when all bind participants have failed to authenticate the user.

The bind priority can be any positive integer that is greater than or equal to zero. The priority decreases from zero to higher integers. That is, the participant with least number has the highest bind priority, the participant with the next least number has the next higher bind priority, and so on. Zero has the highest priority.

If there is only one bind participant, then the bind error message from that participant is returned if the bind fails. However, if there are multiple bind participants, then the bind error message from the primary participant is returned if the bind fails for all the participants.

12.5.1.10 About DN Attributes Translation

DN attributes is a list of attributes to be treated as DNs for which namespace translation is required, such as member, uniquemember, and manager. For example, when reading a group entry from a proxied directory, Join workflow element converts the DN for the group entry and the uniquemember or member attributes if these attributes are in the DN attributes list.

Note:

Translate only those attributes that are needed by the client application. Entering all possible DN attributes may not be necessary for an application.

12.5.1.11 Configuring the Criticality of Join Participants

The criticality configuration parameter determines how the Join workflow element behaves when a search being performed against a participant fails due to a host error. Criticality applies only to search requests.

  • WRITE operations are always critical in all participants.

  • BIND and COMPARE operations are always non-critical in all participants, so that they can fall-through all eligible participants until a success is found.

To configure criticality for a Join participant, use the dsconfig set-join-participant-prop subcommand and set one of the following criticality flag values:

  • true (default setting)

    This setting indicates that the participant is considered critical. If a participant fails to return a result because of an operation error, then the Join workflow element causes the overall search operation to fail and returns a DSA Unavailable error to the client, regardless of whether data was found in any other participant or not.

  • false

    This setting indicates to the Join workflow element that the failure to perform an operation in the participant is not critical to the overall result. If a non-critical participant incurs an operations error, then that result is omitted from the overall LDAP search results. The Join workflow element returns partial results from any other participant and does not indicate any error.

  • partial

    This setting indicates that the participant is partially critical, which implies that the application can notify its own users that partial results were obtained. If a partially-critical participant fails to return a result because of an operation error, then the Join workflow element returns not only partial results but also an Admin Limit Exceeded error. While this is not the expected error, the intention of this setting is to cause client application logic to indicate that not all results are shown.

For example, the following command sets the criticality of a participant named joinparticipant-1 to true: 

dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file \ set-join-participant-prop --element-name we-join \
--participant-name joinparticipant-1 \
--set participant-criticality:true
12.5.1.12 Understanding Enabled Operations

You use the ds-cfg-enabled-operation parameter to configure which LDAP operations to perform on a Join participant. These operations include:

  • ADD

  • BIND

  • COMPARE

  • DELETE

  • MODIFY

  • MODIFYDN

  • SEARCH

The participant can participate only in the operations that you specify in this parameter.

  • The COMPARE, DELETE, MODIFY, and SEARCH operations are enabled by default.

  • You must configure BIND as an enabled operation to allow a participant to participate in bind operations. If you enable the BIND operation, then the configured bind priority determines the participant's priority when the bind is processing.

  • The ADD and MODIFYDN operations are not enabled by default.

    • If the Join is a shadow join, you can enable ADD and MODIFYDN on primary and secondary participants.

    • If the Join is not a shadow join, you can only enable ADD and MODIFYDN on the primary participant.

12.5.1.13 Understanding How to Cascade Write Operations to Secondary Participants

You can cascade write operations, such as DELETE and MODIFY, to secondary participants. That is, if you delete an entry a primary participant, then the related entries in all secondary participants are also deleted. However, this cascading operation is applicable only when you configure the DELETE operation as an enabled operation in the associated secondary participant and the relationship between the original participant and the to-be-cascaded-delete participant is not many-to-one.

MODIFY operations are also cascaded to all eligible secondary participants based on their enabled-operations configuration and storable attribute configuration. ADD and MODIFYDN are cascaded only to shadow secondary participants based on the storable attributes configured in those participants.

12.5.1.14 Understanding How to Use the Join Workflow Element to Implement Pass-Through Authentication

You can configure the Join workflow element to delegate bind requests to the Authentication (Auth) Provider workflow element and non-bind requests to the User Provider workflow element, as depicted in Figure 12-19. This configuration also takes care of delegating MODIFY PASSWORD requests to the Auth Provider workflow element and other MODIFY operations to the User Provider workflow element.

Figure 12-19 Pass-Through Authentication Using the Join Workflow Element

Description of Figure 12-19 follows
Description of "Figure 12-19 Pass-Through Authentication Using the Join Workflow Element"

Note:

For a simple pass-through authentication scenario, use the pass-through authentication workflow element described in Overview of the Pass-Through Authentication Mechanism.

Use the Join workflow element to configure pass-through authentication only if you have special requirements that cannot be met by using the pass-through authentication workflow element. For example, the pass-through authentication workflow element does not route bind requests to the User Provider workflow element, and the user password is stored only in the Authentication Provider workflow element. If you want a different deployment scenario, where you want to store the user password in both the Authentication Provider workflow element and the User Provider workflow element, then you can use the Join workflow element and configure both providers to handle bind requests.

12.5.1.15 Handling LDAP Operations in Join Workflow Elements

If an attribute exists in both the primary and secondary participants, then the Join workflow element merges the attribute values. For read operations, this implies that a multi-valued attribute is returned with the values from all participants. For write operations, the proxy queries all participants and determines where to write the value based on the storable attributes configured in each Join participant.

This section contains the following topics:

12.5.1.15.1 Considerations for Configuring the Join Workflow Elements

When configuring the Join workflow element, you must keep the following points in mind:

  • When you have multiple attributes with the same name from multiple data sources, such as two uid attributes from two different Proxy LDAP workflow elements, the Join workflow element only displays a single value.

    However, you can configure the Join workflow element to retrieve attribute values from a specific participant. To do this, remove the attributes from the Retrievable Attributes field for any participants for whom you do not want to view the attribute.

  • You must configure virtual ACIs correctly to grant or deny entries and attributes from a Join workflow element.

  • When using a Proxy LDAP workflow element as a Join participant, the credentials you use to perform operations in each participant plays a significant role, as follows:

    • If you configure the use-specific-identity bind mode in the Proxy LDAP workflow element, then only a specific identity is used for all non-bind operations.

    • If you configure the use-client identity bind mode in Proxy LDAP workflow element, then actual client credentials are used when userDN is a descendant of any of the DNs configured in the include-list of a Proxy LDAP workflow element. Otherwise, Oracle Unified Directory uses a specific identity to perform operations in the Proxy LDAP workflow element.

    • All Proxy LDAP workflow elements must set the include-list to the respective user container DNs so that the bind correctly happens either with the client DN or with a specific identity. This configuration also requires each participant's user container to be unique, or the bind fails.

    • You must always configure the proxy and root credentials in the Proxy LDAP workflow element because some internal operations use those credentials. These credentials are also required when you configure a include-list in a Proxy LDAP workflow element.

12.5.1.15.2 Processing LDAP Operations Using the Join Workflow Element

Table 12-3 describes how the Join Workflow element processes each LDAP operation.

Note:

The Join workflow element displays a single value only, if there are multiple attributes with the same name from multiple data sources, for example two uid attributes from two different Proxy LDAP workflow elements. However, you can configure the Join workflow element to retrieve attribute values only from a specific participant. To view the attribute from a specific participant only, you must ensure that the attribute is not listed in the Retrievable Attributes field for the participant for which you do not want to show the attribute for.

Table 12-3 How the Join Workflow Element Processes LDAP Operations

LDAP Operation Processing Description

ADD

  • Processed in the primary participant based on storable attributes and enabled operation.

  • Processed only in shadow secondary participant based on storable attributes configured in that participant.

  • For other Joiners, no processing is done for secondaries.

    Store entry in the secondary participant if at least one attribute (except the link attributes) must be stored in the shadow.

    Typical shadow Join participant has storable attributes set. Implicitly add link attributes to storable.

  • Implicitly treat all Join attributes as storable, unless they are configured in the unstorable attributes list.

BIND

Processed in each bind participant based on bind priority.

COMPARE

  • Processed in primary participant based on retrievable attributes and enabled operation.

  • If COMPARE failed in primary participant, then COMPARE is processed in all secondaries based on retrievable attributes and enabled operations.

DELETE

  • Processed for all participants where DELETE is enabled.

  • Not processed for participants that are on 1 side of a many-to-one relationship.

MODIFY

  • Processed in primary participant based on storable attributes and enabled operation.

  • For secondaries (any Joiner type), process modification if attributes are storable attributes.

  • For a Shadow Joiner

    Modify the shadow entry if the MODIFY attribute must be stored in the shadow participant.

    If the shadow entry is missing, then create a new entry to store the MODIFY attribute if the attribute must be stored in the shadow participant.

    If the shadow entry is retrieved by searching a second shadow, then rename the shadow entry to a correct value.

  • For all Joiner types, implicitly treat all attributes as unstorable to maintain the link. Does not allow modification of link attribute through the Join workflow element. The operation succeeds, but the link attribute is not modified.

  • In all participants where the MODIFY attribute is not a link attribute, the modification takes place if that attribute is defined as storable.

MODIFYDN

  • Processed in primary participant based on enabled operation.

  • For Shadow Joiner, update the shadow entry DN.

  • For other Joiner types, no processing done for secondary participants.

  • For all Joiners, does not allow MODDN for link attributes and if deleteoldrdn is true.

SEARCH

Processed in primary participant first. Then, joins the entry with all eligible secondary participants for each entry returned from the primary that satisfies the Join condition.

12.5.2 Overview of Optimizing Search Results From Virtual Directories Using Workflow Elements

Oracle Unified Directory provides two workflow elements that automatically narrow search results to help you more efficiently view or retrieve data from virtual data sources.

You can insert the following workflow elements into any workflow that returns search results:

  • GetRidofDuplicate

    The GetRidofDuplicate workflow element removes, from search results for the current search operation, all the entries whose DN has already been returned to the client application. This is useful when a workflow element is likely to return several entries, maybe hundreds, with the same DN.

  • HideByFilter

    The HideByFilter workflow element enables you to control in fine detail which entries are returned by search operations. For example, if you use Oracle Unified Directory as an address book directory, you can display only the entries for customer service representatives. First, give customer service representatives an ou value such as CSR. Then you can use the HideByFilter workflow element with the hideByFilter set to ou=CSR. When the directory is searched, only the customer service representatives entries are returned.

For detailed information about configuring the GetRidOfDuplicates and HideByFilter workflow elements, see Optimizing Search Results From a Virtual Directory.

12.5.3 Understanding Addition of memberof User Attributes to person Entries

You can configure the VirtualMemberof workflow element to add the memberof user attribute to person entries, which is useful when you want applications see group membership, but do not want them to perform secondary searches for those groups.

The memberof attribute values are the DNs of any groups to which the person entry belongs.

Note:

The VirtualMemberOf workflow element only impacts the SEARCH operation

For information about creating and configuring a VirtualMemberof workflow element, see Adding the memberof User Attribute to person Entries.

You can use the memberof attribute in a search filter (for example, MemberOf=group1); however, memberof does not support the following combinations:

  • PRESENT, SUBSTRING, GREATER_OR_EQUAL, LESS_OR_EQUAL for memberof

  • OR filter with an inner memberof component

  • NOT filter with an inner memberof component

  • Pattern-based search filter, such as a wildcard character (for example, memberOf=cn=*)

Based on these restrictions, an inner memberof component is supported only in AND filters.

When you use the memberof attribute in the search filter, Oracle Unified Directory only returns entries with objectclass=person. The VirtualMemberof workflow element does not support using the memberof attribute on a non-person entry.

12.5.4 Overview of Renaming DNs Using the Proxy

You can rename DNs using the proxy as explained in the following topics.

This section includes the following topics:

12.5.4.1 About 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.

Note:

For information about configuring DN renaming, see Performing DN Renaming.

12.5.4.2 Understanding 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 12-20 illustrates how DN renaming is performed using the proxy.

Figure 12-20 DN Renaming

Description of Figure 12-20 follows
Description of "Figure 12-20 DN Renaming"

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 either DNs or Name And Optional UIDs syntax

    For example, the server-side value of the manager attribute of an entry with an objectclass inetorgperson has a DN syntax: manager: uid=mgr,ou=people,dc=server,dc=com and is transformed into the value manager: uid=mgr,ou=myorg,dc=server,dc=com on the client side.

    In another example, the server-side value of the uniquemember attribute has a Name And Optional UID syntax (as defined in RFC 4517) as uniquemember: uid=member,ou=people,dc=server,dc=com#'0111'B and is transformed into the value uniquemember: uid=member,ou=myorg,dc=server,dc=com#'0111'B 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.

12.5.5 Understanding How to Modify RDN Values Using the Proxy

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

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

Note:

For information about configuring RDN changing, see Performing RDN Changing Configuration.

Figure 12-21 illustrates how RDN changing is performed using the proxy.

Figure 12-21 RDN Changing

Description of Figure 12-21 follows
Description of "Figure 12-21 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.

12.5.6 Understanding How to Retrieve Attributes from a SAML Identity Provider Using SAML XASP

Oracle Unified Directory provides a workflow element that retrieves attributes from a SAML Identity Provider using the SAML X.509 Attribute Sharing Profile.

For more information on how to create a new SAML XASP workflow element or how to modify the properties of an existing workflow element, see Configuring SAML XASP.

12.5.6.1 Overview of SAML XASP Workflow Element

The SAML XASP workflow element allows Oracle Unified Directory to retrieve attributes from a SAML Identity Provider using the SAML X.509 Attribute Sharing Profile.

Oracle Unified Directory sends SAML V2.0 assertion queries to an identity provider. The content of the SAML response is then used to build an entry that will be returned by the SAML XASP workflow element.

The SAML XASP workflow element can operate on three types of search operations:

  • A subtree search on the custom adapter base with a filter containing (certificatedn=cn=user1,cn=users,dc=example,dc=com)

    This search is transformed into a SAML V2.0 assertion query requesting the information for the subject cn=user1,cn=users,dc=example,dc=com. If the query returns an entry, this entry is added in the cache and indexed by its cn.

  • A base search on the cn=user1,cn=users,dc=example,dc=com entry

    This search is transformed into a SAML V2.0 assertion query requesting the information for the subject cn=user1,cn=users,dc=example,dc=com or returns the entry if it is already contained in the cache.

  • A subtree search on the custom adapter base with a filter containing (cn=user1)

    The entry is searched in the cache.

Note:

In the preceding descriptions, you can replace certificatedn with the value of the xasp-attribute-name configuration parameter, and cn with the value of the xasp-index configuration parameter.

12.5.6.2 Configuration Parameters for SAML XASP Workflow Element

Learn about the various SAML XASP workflow element configuration parameters, their names, descriptions, allowable values and formats, and rules to perform an action based on the values provided, from the tabular column below.

Table 12-4 describes the configuration parameters needed to configure SAML XASP workflow element:

Table 12-4 Configuration Parameters for SAML XASP Workflow Element

Property Description Mandatory or Optional Value

xasp-ws-url

Defines the web service URL of the identity provider.

Mandatory

String

For example, http://hostname:port/fed/ar/soap.

xasp-attribute-name

Defines the attribute that contains the DN of the entry in the search filter.

Mandatory

String

For example, certificatedn.

xasp-contains-dn

Defines a string that must be part of the DN of the entry.

For example, dc=example.

If the DN of the entry does not contain this exact string (ignoring case), then the entry is not returned. This parameter allows the workflow element to restrict the searches to a portion of the DIT, for example only entries below cn=users. If you do not want to restrict the searches, specify dc=example.

Mandatory

DN

For example, dc=example.

xasp-base-dn

Base DN to be used in case the value is not present in filter.

Mandatory

DN

For example, dc=example,dc=com.

xasp-ttl

Defines the Cache Time-To-Live in milliseconds (Default value and minimal value is 5000).

Optional

String

xasp-debug

Specifies whether to log additional messages.

  • true: Log additional messages.

  • false: Do not log additional messages. (Default)

Optional

Boolean

true, false

xasp-reverse-dn

Defines whether the DN contained in the certificate is reversed.

For example, dc=com,dc=example,cn=users,cn=user1.

  • true: Specify if the dn is reversed.

  • false: Specify if the dn is not reversed. (Default)

Optional

Boolean

true, false

xasp-index

Defines a comma-separated list of attributes that is used to index the results.

Note:

To be indexed, this attribute must be part of the SAML response.

Optional

String

For example, cn.

xasp-response

Defines a comma-separated list of attribute value pairs that is added to each returned entry.

Optional

String

For example, department=Sales.

12.5.6.3 Considerations for Using the SAML XASP Workflow Element

Consider the following points while using the SAML XASP workflow element:

  • None of the logical operators have any significance in the LDAP search filter

  • The LDAP search filter works only for xasp-attribute-name and xasp-index (if xasp-attribute-name is not present in the filter)

  • Regular expressions do not work with the LDAP search filter for SAML XASP workflow

12.5.7 Understanding ForkJoin Workflow Element

The ForkJoin workflow element aggregates data from two remote data sources at real time.

This section describes the following topics:

12.5.7.1 Overview of ForkJoin Workflow Element

Oracle Unified Directory supports ForkJoin workflow element. It solves the problem of split-profiles, where the user data is split across two repositories.

The ForkJoin workflow element can have one primary participant and one secondary participant, each of which is a workflow element of any type. The ForkJoin workflow element allows you to search (search filter) against the primary participant, the secondary participant, or both the primary and the secondary participant. However, the Join workflow element allows you to search (search filter) against the primary participant only.

For example, consider a scenario where user data resides in multiple identity sources, with samaccountname, sn, givenname, and employeenumber in Active Directory. However, the title attribute is stored in a Human Resources database. Assume, Active Directory configured as the primary participant and Human Resources database configured as the secondary participant. Now, with ForkJoin workflow element configured, when an LDAP-enabled application queries the user data based on samaccountname, or title, or both then Oracle Unified Directory retrieves user entries based on the filter from both Active Directory and the Human Resources database.

12.5.7.2 About ForkJoin Participants

ForkJoin participants are the workflow elements that are participating in the ForkJoin configuration topology. There are two types of ForkJoin participants, the primary participant and the secondary participant.

The ForkJoin workflow element can have one primary participant and one secondary participant, each of which is a workflow element of any type. You determine which participant is primary.

For each data backend (LDAP or RDBMS), you must create either a Proxy LDAP workflow element or RDBMS workflow element that is associated with the backend to retrieve information from that backend. You can then formulate these workflow elements as participants of a ForkJoin workflow element topology.

Note:

See Implementing ForkJoin Workflow Element Configuration Model to learn how to deploy a ForkJoin configuration.

You must keep the following points in mind while implementing ForkJoin workflow element configuration:

  • ForkJoin workflow element configuration supports only a single secondary participant.

  • ForkJoin workflow element configuration allows simple Join rule of the format primary-participant-attribute=secondary-participant-attribute. For instance, sn=cn where sn is the attribute in the primary participant and cn is the attribute in the secondary participant.

  • When join-policy is set to full-outer-join and BIND operation is enabled on secondary participant, then bind is allowed even for secondary-only users that do not exist in the primary participant at all.

12.5.7.3 Configuration Parameters for ForkJoin Workflow Element

Learn about the various ForkJoin workflow element configuration parameters, their names, descriptions, and functionality.

The following table describes the ForkJoin workflow element configuration parameters:

Table 12-5 Configuration Parameters for ForkJoin WorkFlow Element

Property Description Mandatory or Optional Value
cache-size

Defines the maximum number of entries that can be stored in the cache used to filter out entry duplicates. When the entry duplicates filtering is active, the ForkJoin workflow element stores the returned entry DNs in a cache. A cache is specific to a search operation, and when the cache is full, the search operation is aborted. By default, the cache can handle 10000 DNs. When the cache size is set to 0 or is negative, then no limit is enforced.

Optional 10000
dn-attribute Defines the DN syntax attribute whose DN need to be translated to that of ForkJoin workflow element. Optional manager, member, memberof, uniquemember
enabled Indicates whether the workflow element is enabled for use in the server. If a workflow element is not enabled, then its contents are not accessible when processing operations. Mandatory true, false
join-suffix Defines the virtual DN that will be exposed by the ForkJoin workflow element. Mandatory A valid DN, for example dc=example,dc=com.
populate-joinedentrydn Decides if the attribute joinedentrydn has to be populated in the joined entries. Optional true, false
primary-and-secondary-attributes Defines a list of attributes that are present in both the primary and secondary participants and which the application can use in the search filter. The attributes identified by the primary-and-secondary-attributes configuration parameter cannot also be identified by the secondary-only-attributesconfiguration parameter.

The objectclass attribute is always considered as primary-and-secondary-attributes by default, even if not explicitly configured.

Optional The name of an attribute type defined in the server schema.
secondary-only-attributes Defines a list of attributes that are present only in the secondary participant and which the application can use in the search filter. The attributes identified by the secondary-only-attributes configuration parameter cannot be identified by the primary-and-secondary-attributes configuration parameter. Optional By default, the secondary-only-attributes attributes list is empty, which means that participant is not responsible for handling any attributes that are present in search filter. When it is empty for all the participants then all search attributes are considered to be in primary participant. The value is the name of an attribute type defined in the server schema.
join-policy Defines the Join policy configuration for this ForkJoin workflow element, which decides what entries are returned from search operation. This is analogous to Database join.

It supports the following values:

  • standard-join: Returns all entries that satisfy the search filter in the primary participant after joining the corresponding entries in secondary participants.

  • left-outer-join: Returns all the entries in the primary participant after joining with corresponding entries in secondary participant (standard-join), and returns entries from the secondary participant that satisfy the join condition and which have a corresponding match in primary participant. This is the equivalent to Left Outer Join in database terminology.

  • full-outer-join: Returns all the entries in the primary participant after joining with corresponding entries in secondary participant (standard-join); returns entries from the secondary participant that satisfy the join condition and which have a corresponding match in primary participant (left-outer-join); and returns entries from the secondary participant that satisfy the search filter but do not have a matching entry in primary participant. This is the equivalent to Left Outer Join + Right Outer Join in database terminology.

For conditional joins when full-outer-join is configured, the entries in secondary participant are mapped to entries in primary participant without considering the filter in join condition.

Mandatory standard-join, left-outer-join, full-outer-join

Note:

At a minimum, you must set either the secondary-only-attributes or primary-and-secondary-attributes configuration parameter to implement the ForkJoin workflow element. See Implementing ForkJoin Workflow Element Configuration Model to learn how to deploy a ForkJoin configuration.

12.5.8 Understanding DynamicGroups Workflow Element

The DynamicGroups Workflow Element operates by monitoring the returned LDAP objects and detects the entries where the memberURL attribute is present and the objectclass is groupOfURLs.

This section contains the following topics:
12.5.8.1 Overview of DynamicGroups Workflow Element

The DynamicGroups Workflow Element enables Oracle Unified Directory to process LDAP objectclasses that are groupOfUrls (referred to as a "dynamic group") and convert it into a virtual static group or groupOfUniqueNames equivalent.

The DynamicGroups Workflow Element automatically processes any memberURL values and adds the results to the uniqueMember attribute. This dynamic object processing allows administrators to define groups that hold both static members and dynamic members while maintaining compatibility with applications that may not normally support the groupOfUrls objectclass.

For example, consider the search query as follows:

ldapsearch -D bindDN -q -b ou=groups,ou=airius,o=yourcompany.com -s sub "(memberurl=*)"

cn=test,ou=groups,ou=airius,o=yourcompany.com
cn=test
memberURL=ldap:///ou=accounting,o=yourcompany.com??sub?(&(objectclass=person)(obj
ectclass=organizationalperson))
objectclass=groupofUniqueNames
objectclass=groupOfUrls
objectclass=top
uniqueMember=cn=Paul Jacobs,ou=People,ou=Airius,o=yourcompany.com
uniqueMember=cn=Wendy Verbaas,ou=People,ou=Airius,o=YourCompany.com

cn=TestCheck,ou=groups,ou=airius,o=yourcompany.com
memberURL=ldap:///ou=alt bind,o=yourcompany.com??sub?(cn=*)
objectclass=groupofUniqueNames
objectclass=groupOfUrls
cn=TestCheck

In the above example, two groups are returned. The first group holds two static members and has a memberURL defining a particular directory subtree to also be members.

When the DynamicGroups Workflow is enabed, the same query results as follows: 

./ldapsearch -D bindDN -q -b ou=groups,ou=airius,o=yourcompany.com -s sub "(cn=test)"
uniqueMember
cn=test,ou=groups,ou=airius,o=yourcompany.com
memberURL=ldap:///ou=accounting,o=yourcompany.com??sub?(&(objectclass=person)(obj
ectclass=organizationalperson))
objectclass=groupOfUniqueNames
objectclass=groupOfUrls
objectclass=top
cn=test
uniqueMember=cn=Paul Jacobs,ou=People,ou=Airius,o=yourcompany.com
uniqueMember=cn=Wendy Verbaas,ou=People,ou=Airius,o=YourCompany.com
uniqueMember=cn=Vipi Velasquez,ou=accounting,o=yourcompany.com
uniqueMember=cn=Preston Pena-Fernandez,ou=accounting,o=yourcompany.com
uniqueMember=cn=Andreas O'Hara,ou=accounting,o=yourcompany.com
uniqueMember=cn=Chitra Guenette,ou=accounting,o=yourcompany.com
...
uniqueMember=cn=Jim Ward,ou=accounting,o=yourcompany.com

The DynamicGroup Workflow Element expands the memberURL value (that is, it executes an LDAP search query with the base, scope, and filter specified in the memberURL and adds the returned DNs to the member attribute) if, and only if, the search filter specified in the client request does not return any entries from a backend directory.

To know more about how the DynamicGroup Workflow Element expands the memberURL , see Testing the DynamicGroups With and Without Expanding memberURL Attribute

12.5.8.2 Configuration Parameters for DynamicGroups Workflow Element

Learn about the configuration parameters for DynamicGroup Workflow Element and their functionality.

The following table describes the allowed properties and their description.

Table 12-6 Configuration Parameters for DynamicGroups Workflow Element

Property Description Mandatory or Optional Default Value
check-url-base

Defines whether or not to honor the base and scope specified in memberURL while performing membership queries

Optional

False
enabled

Defines if the property is enabled or not for use in the server. If a Workflow Element is not enabled, then its contents are not accessible when processing operations.

Mandatory

True
Expand-url

Defines whether the dynamic groups have to be expanded or not.

If this value is not explicitly configured, it is implicitly calculated based on the requested attributes of a search request. For implicit calculation, if the requested attributes in a search query request is the member/uniquemember attribute, then the group is expanded. Otherwise, the group is not expanded.

This explicitly configured value will override the implicit behavior.

Optional

-
fetch-both-static-dynamic

Defines whether or not to fetch both static and dynamic groups which a user is a member of.

If set to false, fetches only static groups to which a particular searched user belongs, and it does not fetch the dynamic group.

If set to true, fetches both static and dynamic groups for the searched user.

Optional

False
Global-search

Defines whether or not to perform global search while expanding dynamic group.

If set to true, then the search would be performed against the entire network group which the current workflow element belongs to.

If set to false, then the search would be performed starting from the next workflow element.

Optional

False
member-attribute

Defines the name of the attribute that stores group member values.

This attribute along with the appropriate objectclass would be added to the dynamic group entry after expanding memberURL attribute of the entry.

Optional

uniquemember
next-workflow-element

Defines the next workflow element in the chain of workflow elements

Mandatory

userRoot
user-search-base

Defines the optional value for a virtual search base that needs to override the base specified in an LDAP URL.

Optional

A valid DN

Note:

If expand-url is not defined, the search request for all attributes does not expand dynamic groups. For example, the dynamic group workflow element created with default options, the search query request for all attributes with filter containing cn does not expand dynamic groups.

See Configuring DynamicGroup Workflow Element to learn how to configure dynamic group workflow element.

12.6 Understanding the 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:

  • Entry 1, with uid=user.1 and mail=joe.smith@example.com is sent to partition 1.

  • Entry 2, with uid=user.2 and mail=joe.smith@example.com is sent to partition 2.

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.

Note:

For more information see Configuring Global Indexes Using the Command Line and 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 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 Replicating Global Index Catalogs.

Consider the following example that uses 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.

12.7 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.

Note:

To use the virtual directory capabilities described here, you must have a valid Oracle Directory Service Plus license.

This section describes how transformation in Oracle Unified Directory occurs and contains the following topics:

Note:

For information about configuring transformation, see Configuring Transformations.

12.7.1 Overview of Transformation

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

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.

The topics in this section include:

12.7.1.1 Overview of 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:

12.7.1.1.1 Understanding 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 12-22 illustrates the concept of a read transformation.

Figure 12-22 Read Transformation

Description of Figure 12-22 follows
Description of "Figure 12-22 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 must 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.

12.7.1.1.2 Understanding 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 back end.

Figure 12-23 illustrates the concept of a write transformation.

Figure 12-23 Write Transformation

Description of Figure 12-23 follows
Description of "Figure 12-23 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 must 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.

12.7.1.1.3 Understanding 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 12-24 illustrates the concept of a mapping transformation.

Figure 12-24 Mapping Transformation

Description of Figure 12-24 follows
Description of "Figure 12-24 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.

12.7.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 must:

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

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

Note:

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

12.7.2 Components of Transformation

Understand about the components for configuring the workflow elements for transformation.

The topics in this section are:

12.7.2.1 Overview of Transformation Types

To configure the workflow element of transformation types use 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.

12.7.2.1.1 addOutboundAttribute Transformation Type

The addOutboundAttribute 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 12-7 describes the parameters of addOutboundAttribute transformation type.

Table 12-7 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 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...)
12.7.2.1.2 filterOutboundAttribute Transformation Type

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

Table 12-8 describes the parameters of filterOutboundAttribute transformation type.

Table 12-8 Parameters of FilterOutboundAttribute Transformation Type

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

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

source-attribute

S

M

string

For more information, see 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 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...)
12.7.2.1.3 addInboundAttribute Transformation Type

The addInboundAttribute 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 12-9 describes the parameters of addInboundAttribute transformation type.

Table 12-9 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 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)
12.7.2.1.4 filterInboundAttribute Transformation Type

The filterInboundAttribute 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 12-10 describes the parameters of filterInboundAttribute transformation type.

Table 12-10 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 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...)
12.7.2.1.5 mapAttribute Transformation Type

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

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

Table 12-11 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 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,...)
12.7.2.1.6 Map Object Class Transformation Type

The Map Object Class transformation creates mapping that can make one objectClass appear like another objectClass. For example a source objectClass inetOrgPerson can appear like a client objectClass user. This ability is useful when an application expects a particular objectClass/attributes, but the directory does not support that.

The Map Object Class transformation can perform different types of manipulations based on the selected configuration parameters. These manipulations are attribute mapping, objectclass mapping, adding or removing attributes conditional on objectclass, and filtering object classes during write or modify operations. The Map Object Class transformation takes multiple parameters. The map-objectclass is a mandatory parameter in this transformation. The other parameters are optional.

Table 12-12 Configuration Parameters for Map Object Class transformation

Parameter Description Multi (M) / Single (S) Valued Mandatory (M) / Optional (O) Value

map-objectclass

It maps a client objectclass to a source objectclass during add, modify (only when filter-objectclass-on-modify value is false) and search operations. Its syntax is client-objectclass=source-objectclass.

Example:

user=inetOrgPerson

The client objectclass user is converted to source objectclassinetOrgPerson when sent to the source repository. And it’s converted back from inetOrgPerson to user when read from the source repository and sent to the client application.

M

M

 objectclass=objectclass

add-attribute

It adds an attribute to the entry during the add operation. You may specify a conditional source objectclass name to add an attribute to that entry. The attribute will be added only if the entry contains the source objectclass. In that case, you must prefix the objectclass name to the attribute name with ':' as the separator.

Example:

inetOrgPerson:userAccountControl=546

It will add userAccountControl attribute to the entry if the entry contains the source objectclass inetOrgPerson.

inetOrgPerson:displayName=%cn%

It will add displayName attribute, with value same as cn attribute, to the entry if the entry contains the source objectclass inetOrgPerson.

M

O

 objectclass:attribute

entry-match-filter

 Specifies the filter that the entry must match for this transformation to apply. S

O

String

entry-parent-suffix

 Specifies an ascendant of the operation DN for this transformation to apply. M

O

DN

excluded-operation

 Specifies operations on which this transformation never apply. This allows to restrict the regular behavior of this transformation. M

O

 Operation

filter-attribute

It will remove an attribute from the entry during add, modify, and search operations. You may specify a conditional source objectclass name to remove the attribute from the entry. The attribute will be removed only if the entry contains the source objectclass. In that case, you must prefix the source objectclass name to the attribute name with ':' as the separator.

Example:

accountname

It will remove the accountname attribute from the entry during add, modify, and search operations.

inetOrgPerson:memberof

It will remove the memberof attribute from the entry during add and modify operations. The attribute will be removed only if the entry contains the source objectclass inetorgperson. However, it will not remove the memberof attribute from the entry while reading it from the source.

M

O

objectclass:attribute

filter-objectclass-on-modify

It’s a flag to determine whether or not to remove object classes during modify operations. Supported values include true (remove changes) and false (do not remove changes), where true is the default value.

S

O

Boolean

filter-objectclass-on-write

It remove an objectclass during add and modify operations. For instance, Microsoft Active Directory for Windows 2000 does not allow auxiliary object classes to be listed while adding an entry, while Microsoft Active Directory and ADAM for Windows Server 2003 does allow for auxiliary classes to be listed.

For example, if the value is specified as person, then the person objectclass will be removed from the entry during add and modify operations.

M

O

 Objectclass

map-attribute

It maps a client attribute to a source attribute during add, modify and search operations. It’s syntax is client-attribute=source-attribute.

Example:

displayName=%givenName%

The value of the client attribute displayName is assigned to source attribute givenName when sent to the source repository. It’s reverse assigned from the source attribute givenName to client attribute displayName when its read from the source repository.

This parameter also supports value mapping syntax: o=%ou%(US,SFO)(IN,BGL).

Here, the client attribute o is mapped to the source attribute ou. If the value of o is US, then ou is assigned SFO. Similarly, if the value of o is IN, then ou is assigned BGL. It’s reverse assigned from the source attribute ou to client attribute o when read from the source repository.

M

O

 Attribute
12.7.2.1.7 tokenize-attributeTransformation Type

The tokenize-attribute transformation allows you to apply the transformation on the attribute which has values separated with delimiter.

For example, an attribute attr:a,b,c is split it into multiple values by delimiter and when a tokenize-attribute transformation is applied, it returns as a true multi-valued attribute. Such as:
attr:a
attr:b
attr:c

Table 12-13 describes the parameters of tokenize-attribute Transformation Type.

Table 12-13 Parameters of tokenize-attribute Transformation Type

Parameter Description Multi (M) / Single (S) Valued Optional (O) / Mandatory (M) Values
multivalued-attribute Specifies the name of the attribute whose value will be tokenized with the delimiter as multiple values. M M Attribute
tranformation-value-delemiter Specifies the delimiter to tokenize the attribute value to multiple values.By default the value will be "," S O String
12.7.2.2 Overview of 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:

  • You can configure conditions to rules whether transformations apply or not.

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

  • You can set conditions on each individual transformation and they are evaluated prior to eventually processing this transformation.

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

12.7.2.2.1 About 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.

12.7.2.2.2 About 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.

12.7.2.2.3 About 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.

12.7.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:

12.7.2.3.1 Using 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 \
12.7.2.3.2 Using 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.

12.7.2.3.3 Using 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 \
12.7.2.3.4 Using 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
12.7.2.3.5 Using 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
12.7.2.3.6 Using Tokenized Attribute Transformation

Tokenization is the process of taking the input text (such as a sentence) and then splitting it into individual terms, called tokens. Tokenize attribute transformation applies the transformation on the attribute which has values separated with delimiter then split it into the multiple values by delimiter and returns as a true multi-valued attribute.

In the values provided, delimiter is configurable. By default the delimiter is ‘,’. If the delimiter character itself is part of the value, then it must be escaped using ‘\’ character.

For example, consider the following multi valued attribute for telephoneNumber.

Note that the user.0 has the following details stored: 

dn: uid=user.0,ou=People,dc=example,dc=com 
objectClass: inetorgperson 
uid: user.0 
telephoneNumber: +1 685 622 6202, +1 785 788 4567, +1 456 765 3456

Apply tokenize-attribute transformation on telephoneNumber attribute: 

./dsconfig create-transformation \
--type tokenize-attribute \
--set multivalued-attribute:telephoneNumber \
--transformation-name tokentrans \

Perform a search on the attribute telephoneNumber: 

./ldapsearch -h hostname -p 20389 -D "cn=directory manager" -w password -s sub -b "dc=example,dc=com" "(uid=user.0)" telephoneNumber uid
Here, the tokenize-attribute transformation applies on the telephoneNumber attribute and tokenizes the value with delimiter and gives the value as true multi-valued attribute.It returns user.0 which has multiple values for telephoneNumber:
dn: uid=user.0,ou=People,dc=example,dc=com
telephoneNumber: +1 685 622 6202
telephoneNumber: +1 785 788 4567 
telephoneNumber: +1 456 765 3456
uid: user.0    

12.7.3 Examples of Transformation Use Case Configuration

Understand how to map activation or deactivation for a specific back end directory and how to map object classes.

The following topics illustrate practical uses for transformation, and provide example configurations:

12.7.3.1 Mapping Activation or Deactivation for a Specific Back End Directory

This configuration is useful when an application has its own user activation attribute and values, which is different from the back end user activation attribute and values, and a mapping for read and write operations is required.

In the following example, the attribute myuseraccountcontrol with values activated and deactivated transforms to the back-end attribute nsAccountLock with values false and true for a DSEE (SunONE) back end. 

$ ./dsconfig -X -n -Q -p 1444 -D cn=directory manager -j pwdfile
 create-transformation --transformation-name mapactivate --type map-attribute 
--set client-attribute:myuseraccountcontrol="%nsAccountLock%(activated,false)
(deactivated,true)"

In the following example, the attribute myuseraccountcontrol with values activated and inactivated transforms to back-end attribute userAccountControl with values 544 and 546 for an Active Directory back end. 

$ ./dsconfig -X -n -Q -p 1444 -D cn=directory\ manager -j pwdfile
 create-transformation --transformation-name mapactivate --type map-attribute
 --set client-attribute:myuseraccountcontrol="%userAccountControl%
(activated,544)(deactivated,546)"
12.7.3.2 Mapping Object Classes by Using map-attribute Transformation Type

This configuration is useful when an application has an objectclass with same meaning as an objectclass on the back-end server, but the two objectclasses have different names. A mapping on the objectclass name is required on read and write operations.

In the following example, a search comes in from the client with filter objectClass=User, and you want to transform that filter to objectClass=inetOrgUser. When an entry is returned to the client, if the entry is stored with the objectClass=inetOrgUser, then the entry is mapped to objectClass User. 

$ ./dsconfig -X -n -Q -p 1444 -D cn=directory manager -j pwdfile
 create-transformation --transformation-name mapoc --type map-attribute 
--set client-attribute:objectClass="%objectClass%(User,inetOrgUser)"
 
$ ./dsconfig -X -n -Q -p 1444 -D cn=directory manager -j pwdfile
 create-workflow-element --type transformations  --element-name trsfwfe 
--set enabled:true --set next-workflow-element:userRoot --set transformation:mapoc
$ ./dsconfig -X -n -Q -p 1444 -D cn=directory manager -j pwdfile set-workflow-prop
 --workflow-name userRoot0 --set workflow-element:trsfwfe

Note:

It is recommended to use map-object-class Transformation Type to map object classes.
12.7.3.3 Mapping Object Classes by Using map-object-class Transformation Type

The Map Object Class transformation creates mapping that can make one objectClass appear like another objectClass. For example a source objectClass inetOrgPerson can appear like a client objectClass user. You can create a new Map Object Class transformation by using the dsconfig command. The map-objectclass parameter is a mandatory parameter to create a Map Object Class transformation.

To create the new transformation:
  1. Run the dsconfig command as shown below:
    $ ./dsconfig create-transformation --type map-object-class --transformation-name ocm2 --set map-objectclass:user=inetOrgPerson -h localhost -p 10444 -D "cn=Directory Manager" -j /pwd-file1.txt
    >>>> Configure the properties of the Map Object Class Transformation

        Property                      Value(s)
        ------------------------------------------------
    1)  add-attribute                 -
    2)  entry-match-filter            -
    3)  entry-parent-suffix           -
    4)  excluded-operation            -
    5)  filter-attribute              -
    6)  filter-objectclass-on-modify  true
    7)  filter-objectclass-on-write   -
    8)  map-attribute                 -
    9)  map-objectclass               user=inetOrgPerson

    ?)  help
    f)  finish - create the new Map Object Class Transformation
    q)  quit

Enter choice [f]: f

The Map Object Class Transformation was created successfully

Note:

It is recommended to use map-object-class Transformation Type to map object classes.
12.7.3.4 Adding Attributes to Source Object Class by Using map-object-class Transformation Type

This example will add displayName attribute, with value same as cn attribute, to the entry if the source objectclass is inetOrgPerson. 

dsconfig set-transformation-prop --transformation-name ocm2 --set add-attribute:inetOrgPerson:displayName=%cn% -n -X -h localhost -p 10444 -D "cn=Directory Manager" -j /pwd-file1.txt
12.7.3.5 Filtering Attributes from Source Object Class by Using map-object-class Transformation Type

This example will remove the memberof attribute from the entry with source objectclass inetOrgPerson, during add and modify operations. However, it will not remove the memberof attribute from the entry while reading it from the source. 

dsconfig set-transformation-prop --transformation-name ocm2 --add filter-attribute:inetOrgPerson:memberof -n -X -h localhost -p 10444 -D "cn=Directory Manager" -j /pwd-file1.txt