24 Configuring Virtualization

This chapter describes how to configure virtualization.

This chapter includes the following sections:

Note:

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

Note:

You can choose to configure some virtualization elements using dsconfig or Oracle Directory Services Manager (ODSM).

24.1 Configuring a Virtual Directory View of Your Repositories

This section describes how to create and configure a Join workflow element to create a virtual directory view of your repositories.

Note:

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

This section includes the following topics:

24.1.1 Before You Begin

Before creating the Join workflow element, you must configure the participating workflow elements so you can link to them from the Join workflow element configuration.

For example, consider a scenario with two separate Proxy LDAP workflow elements:

  • The first Proxy LDAP workflow element, we-proxy1, will be linked to the primary participant of the Join workflow element configuration.

  • The second Proxy LDAP workflow element, we-proxy2, will be linked to the secondary participant of the Join workflow element configuration.

Note:

For more information about creating Proxy LDAP workflow elements, see Section 20.2.2, "Configuring Proxy LDAP Workflow Elements."

Assume there is an entry in the we-proxy1 data source as follows:

dn:cn=john,cn=users,dc=com1
objectclass:inetorgperson
cn:john
sn:doe
uid:jdoe
title:PMTS
description: This entry is from we-proxy1

Next, assume there is an entry in the we-proxy2 data source as follows:

dn: sn=doe,cn=employees,dc=com2
empid: jdoe
cn:John
sn:doe
department: Sales
manager: userid=smith,cn=users,dc=com2
description: This entry is from we-proxy2
objectclass:inetorgperson

The joined-entry returned from Join Workflow element would be:

dn:cn=john,cn=users,dc=join
objectclass:inetorgperson
cn:john
sn:doe
uid:jdoe
empid: jdoe
title:PMTS
description: This entry is from we-proxy1
description: This entry is from we-proxy2
manager: userid=smith,cn=users,dc=join
department: Sales

24.1.2 Creating a Join Workflow Element Using the dsconfig Command

This section describes how to create and configure a Join workflow element topology, based on the scenario using the two Proxy LDAP workflow elements described in Section 24.1.1, "Before You Begin."

Note:

The following steps assume that you have already created the participating workflow elements.

To configure a Join workflow element topology:

  1. Create a Join workflow element, named we-join.

    dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X 
-n create-workflow-element --set enabled:true --set join-suffix:dc=join
--type join --element-name we-join

    >>>> Specify Oracle Unified Directory LDAP connection parameters
 
Directory server hostname or IP address [ip]:
 
Directory server administration port number [4444]:
 
Administrator user bind DN [cn=Directory Manager]:
 
Password for user 'cn=Directory Manager':
 
 
>>>> Configure the properties of the Join Workflow Element
 
        Property                Value(s)
        ---------------------------------------------------------------
    1)  dn-attribute            manager, member, memberof, uniquemember
    2)  enabled                 true
    3)  join-suffix             dc=join
    4)  populate-joinedentrydn  false
 
    ?)  help
    f)  finish - create the new Join Workflow Element
    q)  quit
 
Enter choice [f]: f
 
The Join Workflow Element was created successfully

  2. Create a primary participant, named jp-p1, that is linked to the Proxy LDAP workflow element named, we-proxy1.

    dsconfig create-join-participant --element-name we-join \
--set participant-dn:dc=com1 \
--set participating-workflow-element:we-proxy1 \
--set primary-participant:true --type generic --participant-name jp-p1 \

    Provide the following information to create a primary participant:

    >>>> Specify Oracle Unified Directory LDAP connection parameters
 
Directory server hostname or IP address [ip]:
 
Directory server administration port number [4444]:
 
Administrator user bind DN [cn=Directory Manager]:
 
Password for user 'cn=Directory Manager':
 
 
>>>> Configure the properties of the Join Participant
 
         Property                        Value(s)
         ----------------------------------------------------------------------
    1)   enabled-operation               compare, delete, modify, search
    2)   join-condition                  By default, no join condition is
                                         defined. That is all entries
                                         satisfying the original search filter
                                         are considered for join.
    3)   joiner-type                     one-to-one
    4)   non-retrievable-attribute       By default, the non-retrievable list
                                         is empty, which means that all
                                         attributes are retrievable.
    5)   non-storable-attribute          By default, the non-storable list is
                                         empty, which means that all attributes
                                         are storable.
    6)   participant-bind-priority       0
    7)   participant-criticality         true
    8)   participant-dn                  dc=com1
    9)   participants-join-rule          ""
    10)  participating-workflow-element  we-proxy1
    11)  primary-participant             true
    12)  retrievable-attribute           By default, the retrievable list is
                                         empty, which means that all attributes
                                         are retrievable.
    13)  storable-attribute              By default, the storable list is
                                         empty, which means that all attributes
                                         are storable.
 
    ?)   help
    f)   finish - create the new Join Participant
    q)   quit
 
Enter choice [f]: f

The Join Participant was created successfully.

  3. Create a secondary participant, named jp-p2, that is linked to the Proxy LDAP workflow element named, we-proxy2.

    dsconfig create-join-participant --element-name we-join \
--set participant-dn:dc=com2 \
--set participating-workflow-element:we-proxy2 \
--set primary-participant:false --type generic --participant-name jp-p2 \
--set participants-join-rule:jp-p1.uid=jp-p2.empid

    Provide the following information to create a secondary participant:

    >>>> Specify Oracle Unified Directory LDAP connection parameters
 
Directory server hostname or IP address [ip]:
 
Directory server administration port number [4444]:
 
Administrator user bind DN [cn=Directory Manager]:
 
Password for user 'cn=Directory Manager':
 
 
>>>> Configure the properties of the Join Participant
 
         Property                        Value(s)
         ----------------------------------------------------------------------
    1)   enabled-operation               compare, delete, modify, search
    2)   join-condition                  By default, no join condition is
                                         defined. That is all entries
                                         satisfying the original search filter
                                         are considered for join.
    3)   joiner-type                     one-to-one
    4)   non-retrievable-attribute       By default, the non-retrievable list
                                         is empty, which means that all
                                         attributes are retrievable.
    5)   non-storable-attribute          By default, the non-storable list is
                                         empty, which means that all attributes
                                         are storable.
    6)   participant-bind-priority       0
    7)   participant-criticality         true
    8)   participant-dn                  dc=com2
    9)   participants-join-rule          jp-p1.uid=jp-p2.empid
    10)  participating-workflow-element  we-proxy2
    11)  primary-participant             false
    12)  retrievable-attribute           By default, the retrievable list is
                                         empty, which means that all attributes
                                         are retrievable.
    13)  storable-attribute              By default, the storable list is
                                         empty, which means that all attributes
                                         are storable.
 
    ?)   help
    f)   finish - create the new Join Participant
    q)   quit
 
Enter choice [f]: f
 
The Join Participant was created successfully.

  4. To specify which Join policy type to use for a Join workflow element, configure the ds-cfg-join-policy parameter. For example, --set join-policy:left-outer-join.

24.1.3 Creating a Join Workflow Element Using ODSM

If you prefer, you can create a Join workflow element using the ODSM graphical user interface.

Note:

For information, see Section 17.3.4.1, "Creating a Workflow Element."

24.2 Optimizing Search Results From a Virtual Directory

To help you more efficiently view or retrieve data from virtual data sources, Oracle Unified Directory provides two workflow elements that automatically narrow search results. You can insert the GetRidOfDuplicate or HideByFilter workflow elements into any workflow chain that returns search results.

This section includes the following topics:

For more information about Oracle Unified Directory workflows, see "OUD Plug-Ins and Workflows" in Oracle Fusion Middleware Developer's Guide for Oracle Unified Directory.

24.2.1 Eliminating Duplicate Entries from Search Results Using the GetRidofDuplicate Workflow Element

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 with the same DN.

To eliminate duplicate entries from search operations:

Add the GetRidOfDuplcate workflow element before any workflow element, such as the Join workflow element, that returns duplicate entries.

24.2.1.1 Sample Configuration

The following example creates a get-rid-of-duplicate WFE (next WFE=NEXT_WFE).

dsconfig create-workflow-element \
          --set enabled:true \
          --set next-workflow-element:NEXT_WFE \
           --set cache-size:1000000 \
          --type get-rid-of-duplicate \
          --element-name example \
          --hostname locahost \
          --port 1444 \
          -X \
          --bindDN cn=Directory\ Manager \
          --bindPasswordFile ****** \
          --no-prompt

In this example, a search will return no more than 1000000 unique entries.

Note:

In this configuration example, the created workflow element is not part of any workflow chain. A full configuration must also define or create the workflow chain, and update the Network group.

24.2.1.2 Configuration Parameter

The GetRidofDuplicate has one configuration parameter:

cache-size

The cache-size parameter is required. It specifies the maximum number of entries that can be returned to the client during a single search operation.

24.2.2 Filtering Search Results Using the HideByFilter Workflow Element

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

To filter search results using the HideByFilter workflow element:

Create and link a HideByFilter workflow element. For example:

dsconfig create-workflow-element \
          --set enabled:true \
          --set next-workflow-element:NEXT_WFE \
          --set ldap-filter:ou=CSR \
          --type hide-entries-by-filter \
          --element-name example1 \
          --hostname dosapano \
          --port 1444 \
          -X \
          --bindDN cn=Directory\ Manager \
          --bindPasswordFile ****** \
          --no-prompt

24.2.2.1 Configuration Parameters

Table 12-3 summarizes the HideByFilter plug-in configuration parameters:

Table 24-1 HideByFilter Parameters

Parameter Description

hideFilter

  • Static Filter
    Example: If hideFilter = (department=Sales) then only entries with the attribute department=Sales are returned to the client application.

  • Dynamic Filter
    Example: If hideFilter = (department=%department%) then %department% is replaced with the department attribute value of the bound user.

ldapURL (multivalued)

If an entry matches the ldapURL filter then it is returned to the client application only if it's a descendant of the LdapURL base DN. All the other fields of the LDAP filter are ignored.

adapterNames

A list of adapters from which the user entry for the dynamic filter is searched. If list is empty, or if the user entry can be found in none of the adapters (including the current adapter) then the dynamic filter is ignored.

applyForAdmin

When set to true, the filtering does apply to admin users. The parameter is optional and the default value is false.

24.3 Adding the memberof User Attribute to person Entries

This section describes how to add the memberof user attribute to person entries.

Note:

For more information, see Section 12.5.3, "Adding memberof User Attributes to person Entries."

To define a VirtualMemberof workflow element, use the following configuration parameters:

  • searchBase: DN of the base to search for groups containing person entries.

  • explicitRequestOnly: Specify True or False

    • True (default): Adds the memberof attribute to the entry only if it is explicitly requested as a returned attribute.

    • False: Always adds the memberof attribute to the entry.

  • member-attribute-name: The name of the memberof attribute to add.

    Note:

    The memberof attribute has a default value for Oracle Virtual Directory convergence.

    In Oracle Virtual Directory, the memberof attribute is a user attribute (not operational). The definition is:

    attributeTypes: ( 1.2.840.113556.1.2.102 NAME 'memberOf'
  DESC 'The distinguished name of the groups to which this object belongs'
  EQUALITY distinguishedNameMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
  X-ORIGIN 'Microsoft Active Directory' )

24.4 Configuring DN Renaming

To configure DN renaming, you must first create a DN renaming workflow element and then you can modify the following DN renaming properties:

  • client base DN

  • source base DN

  • next workflow element

  • black list attributes

  • white list attributes

This section includes the following topics:

24.4.1 Creating a DN Renaming Workflow Element

To create a DN renaming workflow element, use the dsconfig create-workflow-element command, as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
 create-workflow-element \
 --type dn-renaming \
 --element-name RenameorgDN \
 --set client-base-dn:ou=myorg,dc=example,dc=com \
 --set next-workflow-element:load-bal-we1 \
 --set source-base-dn:ou=people,dc=example,dc=com \
 --set enabled:true

where:

  • --set client-base-dn indicates the client base DN, which is the workflow entry point

  • --set source-base-dn indicates the base DN which the entries should have after transformation, which is the workflow exit point.

  • --set next-workflow-element indicates the workflow element that will follow the DN renaming workflow element in the proxy architecture. You can specify any type of workflow element here.

24.4.2 Modifying a DN Renaming Configuration

You can view and modify a DN renaming configuration by using the following dsconfig commands:

  • To view the current DN renaming properties, use the dsconfig get-workflow-element-prop command.

  • To modify a DN renaming property, use the dsconfig set-workflow-element-prop command. For example,

    $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
 set-workflow-element-prop \
 --element-name RenameorgDN \
 --set source-base-dn:ou=admin,dc=example,dc=com

    In the preceding example, only the source-base-dn is modified. There is no need to specify the old source base DN. Only the new one is required.

  • To create a black list of DN attributes that should not be renamed by using, use the dsconfig set-workflow-element-prop command. For example,

    $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-workflow-element-prop --element-name RenameorgDN \
  --set black-list-attributes:manager

    The attribute must have a DN type.

24.5 Configuring RDN Changing

To change RDNs, you must first create an RDN Changing workflow element, and then you can modify the following properties:

  • client RDN

  • source RDN

  • next workflow element

  • objectclass

  • dn attributes

  • replace-value

Note:

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

This section includes the following topics:

24.5.1 Creating an RDN Changing Workflow Element

To create an RDN Changing workflow element, use the dsconfig create-workflow-element command as follows:

dsconfig create-workflow-element \
          --set client-rdn:cn \
          --set enabled:true \
          --set next-workflow-element:localproxy \
          --set source-rdn:uid \
          --type rdn-changing \
          --element-name myrdnchangingwfe \
          --hostname localhost \
          --port "4444" \
          --trustAll \
          --bindDN cn=directory\ manager \
          --bindPasswordFile pwd-file \
          --no-prompt

where:

  • --set client-rdn indicates the client base RDN, which is the workflow entry point.

  • --set source-rdn indicates the base RDN which the entries should have after transformation, which is the workflow exit point.

  • --set next-workflow-element:localproxy indicates the workflow element that will follow the RDN changing workflow element in the proxy architecture. This can be any type of workflow element.

    Note:

    You must create the Proxy LDAP workflow element with the parameters

    • remote-root-dn

    • remote-root-password

    The RDN Changing workflow element uses these credentials to perform internal searches on the remote server.

  • --element-name myrdnchangingwfe indicates the name of the RDN Changing workflow element you are creating.

    This configuration replaces uid=user.1,ou=people,dc=example,dc=com with cn=User CN,ou=people,dc=example,dc=com.

24.5.2 Modifying RDN Values

After you have configured an RDN changing workflow element, you can view and modify RDN values by using the following dsconfig commands:

  1. To view the current RDN properties, use the dsconfig get-workflow-element-prop command.

  2. To rename or replace an RDN property, use the dsconfig set-workflow-element-prop command.

    $ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
 set-workflow-element-prop \
 --element-name myrdnchangingwfe \
 --set source-rdn:uid

    In the preceding example, only the source-rdn is modified. There is no need to specify the old source-rdn. Only the new one is required.

24.6 Configuring Transformations

This section explains the transformations configuration model and describes two methods for configuring transformations.

Note:

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

This section includes the following topics:

Note:

For more information about transformations, see Section 12.7, "Understanding the Transformation Framework."

24.6.1 Overview of the Configuration Model

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

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

Note:

For detailed information about the various transformation types, conditions, and parameters that you can configure for a transformation workflow element, see Section 12.7.2, "Components of Transformation."

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

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

Figure 24-1 illustrates a high-level configuration model.

Figure 24-1 Configuration Model

Description of Figure 24-1 follows
Description of ''Figure 24-1 Configuration Model''

24.6.2 Configuring Transformation Using dsconfig

This section uses an example to illustrate how to create transformations, create a transformation workflow element, add transformations, and associate conditions using the dsconfig CLI.

Note:

To configure transformation:

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

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

  2. Create another transformation of type add-outbound-attribute.

    $ dsconfig create-transformation -X -n -Q -p -D cn="directory manager" -j pwd-file  \ 
--set client-attribute:legacyemail=%cn%.%sn%@mycompany.com \ 
--type add-outbound-attribute \ 
--transformation-name legacyemail

  3. Create the transformations-workflow-element with the first transformation, and add it to the processing flow.

    $ dsconfig create-workflow-element -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--set transformation:legacyemail \ 
--set set next-workflow-element:pxywfe \ 
--type transformations \ 
--element-name trsfwfe

    $ sdsconfig set-workflow-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--workflow-name pxywf \ 
--set workflow-element:trsfwfe

  4. Add the second transformation to the workflow element.

    $ dsconfig set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--element-name trsfwfe \ 
--add transformation:fodescription

  5. Define the transformation criteria, which is that the transformation will occur only under cn=users.

    $ dsconfig set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--element-name trsfwfe \ 
--set entry-parent-suffix:cn=users,dc=example

  6. Set that transformations will happen only for users located in Paris.

    $ dsconfig set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--element-name trsfwfe \ 
--set entry-match-filter:l=Paris

  7. Create a new mapping transformation and add it to the workflow element.

    $ dsconfig create-transformation -X -n -Q -p -D cn="directory manager" -j pwd-file  \ 
--set client-attribute:faxnum=%facsimileTelephoneNumber% \ 
--type map-attribute \ 
--transformation-name mapfax 

    $ dsconfig set-workflow-element-prop -X -n -Q -p -D cn="directory manager" -j pwd-file \ 
--element-name trsfwfe \ 
--add transformation:mapfax

  8. Set that this transformation will happen only for persons.

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

24.6.3 Configuring Transformations Using ODSM

You can create, modify, and delete a transformation workflow element for Oracle Unified Directory proxy servers using ODSM.

Note:

To create a transformation workflow element using dsconfig, see Section 24.6.2, "Configuring Transformation Using dsconfig."

This section includes the following topics:

24.6.3.1 Creating Transformations

If you are connected to an Oracle Unified Directory Proxy Server, then ODSM allows you to create five different types of transformations. For more information about the types of transformations supported, see Section 12.7.2.1, "Transformation Types."

Note:

If you are connected to an Oracle Unified Directory server instance, then the option to create a new Transformation is not available because transformation functionality is supported by proxy servers only.

To create a transformation using ODSM, follow these steps:

  1. Connect to the directory server from ODSM, as described in Section 16.2, "Connecting to the Server Using ODSM."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. From the Create menu, select Transformation.

  5. From the Transformation submenu, select the desired transformation type.

    Figure 24-2 Transformation Types

    Description of Figure 24-2 follows
    Description of ''Figure 24-2 Transformation Types''

    In this example, consider the following properties for an Outbound Attribute Addition transformation type.

    Note:

    The properties that appear while creating a transformation vary depending on the type of transformation you create. For more information about each transformation type and the associated properties, see Section 12.7.2.1, "Transformation Types."

  6. In the Name field, type the name for the transformation.

  7. In the Conditions region, enter the following information:

    Note:

    Conditions are optional. However; at runtime, conditions specified here at the transformation level are used with those specified at the transformation workflow element level in the transformation workflow element where the transformation is used. For more information about transformation workflow element, see Section 17.3.4, "Configuring Workflow Elements Using ODSM."

    1. In the Entry Matching Filter field, type a valid LDAP filter.

    2. In the Entry Parent Suffixes box, click Add to specify the DN that must be an ascendant.

      To select an entry, click Select.

      In the Entry Picker window, select Tree View to navigate the directory tree and locate the entry, or Search View to search for the entry.

    3. From the Excluded Operations list, select the operations that you want to exclude.

  8. In the Transformation Definition region, enter the following information:

    1. In the Client Attribute field, type the name of the client virtual attribute.

      To select a client attribute entry, click Select.

      In the Attribute Picker window, select locate the desired entry, or Click Search to search for the entry.

    2. In the Value Definitions box, click Add to specify the value definitions of the client virtual attribute.

      Click Define to enter an appropriate value definition. For more information about specifying value definitions, see Section 24.6.3.4, "Selecting Values from Value Definition Screen."

  9. From the Conflict Behavior list, select the desired conflict behavior policy.

  10. Click Virtual in Source to Yes.

  11. Click Create.

24.6.3.2 Modifying Transformations

This section describes how to modify the properties for a transformation. In this example, modify the properties for an Outbound Attribute Addition transformation type created in Section 24.6.3.1, "Creating Transformations."

To modify a transformation, perform the following steps:

  1. Connect to the directory server from ODSM, as described in Section 16.2, "Connecting to the Server Using ODSM."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. Expand the Transformations element.

  5. Click the desired transformation.

    Transformation configuration details appear for modification in the right pane.

  6. Modify the required information.

  7. Click Apply.

24.6.3.3 Deleting Transformations

To delete a transformation, perform the following steps:

  1. Connect to the directory server from ODSM, as described in Section 16.2, "Connecting to the Server Using ODSM."

  2. Select the Configuration tab.

  3. Select the Core Configuration view.

  4. Expand the Transformations element.

  5. Select the desired transformation to delete.

    The Delete configuration window appears seeking confirmation before deleting.

  6. Click OK.

24.6.3.4 Selecting Values from Value Definition Screen

The Value Definition Builder subscreen allows you to define a value for an attribute that is being added, mapped, or deleted by a transformation.

You can specify the following values:

  • Constant value: It is used to enter a constant value.

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

  • Value of expression: It is used to create an attribute value or to filter an attribute value by manipulating the value of one or more existing attributes.

Figure 24-3 shows the Value Definition screen.

Figure 24-3 Value Definition Screen

Description of Figure 24-3 follows
Description of ''Figure 24-3 Value Definition Screen''