Defining Secondary LDAP Sources in an LDAP Container

Each LDAP container that you define must include one primary LDAP source. It can also include one or more secondary LDAP sources.

If there are secondary LDAP sources defined, they will be used to find additional information about each potential resource from the primary LDAP source. Lookups are performed into each secondary LDAP source. If an exact match of a potential resource can be found in every secondary LDAP source, the data from all sources is merged together. In other cases, the potential resource may be omitted or labeled invalid. It determines that based on attribute relationships you specify when adding a secondary LDAP source to your container.

The following are reasons you might want to define a secondary LDAP source:

  • The business process needs to access attribute data that is in both the primary and secondary LDAP sources.
  • the business process needs to access attribute data from an LDAP source that is not used for login authentication (the primary LDAP source is always used for authentication).

As an example, suppose you have two LDAP sources: Acme-Employees and Acme-Developers. The Acme-Employees LDAP source includes sales and support resources, as well as developers. The Acme-Developers LDAP source includes Acme employees who are developers, as well as developer contractors who are not Acme employees. If you want the list of potential resources to include all Acme employees that are developers, and the business process needs attribute data from both LDAP sources, you would add both sources to one container, using filter criteria to filter out all resources other than Acme developers.

Conversely, if the attribute data needed by the business process is available in one of the LDAP sources, it is much more efficient to include only the one LDAP source in the container.

Potential resources are the resources in an LDAP container that can be created and mapped to groups and positions. A list of potential resources is created by the system as follows:

  • It starts with a list of potential resources from the primary LDAP source (that satisfy the specified query string in the primary-ldap.ldap-query parameter of the saveContainer operation).
  • An attempt is made to match those potential resources with entries in each secondary LDAP source. If an exact match is found in every secondary LDAP source, the data from the secondary sources is merged in with the data from the primary source.

    If a potential resource is not found inside one or more of the secondary LDAP sources, the potential resource is eliminated from the list.

    If matches are found in every secondary LDAP source, they must uniquely identify only one LDAP entry in each source. If one or more match multiple items, the item remains in the potential resources list but is marked as invalid.

This primary / secondary match is accomplished by specifying primary-link elements within the secondary-ldap element to which they apply, when calling the saveContainer operation. A primary-link specifies an attribute in the primary LDAP, and the attribute which it must match in each secondary LDAP. In the following example, the secondary LDAP is linked to the primary LDAP using the attributes cn and sn (whose values must match the primary LDAP attributes commonname and surname, respectively):

Request:
<soapenv:Body>
      <dir:saveContainer name="Test Container" description="A test container">
        <primary-ldap ldap-alias="deLdap2" ldap-query="(objectclass=person)" resource-name-attributes="displayname"/>
        <!--Zero or more repetitions:-->
        <secondary-ldap ldap-alias="deLdap3" ldap-query="(objectclass=organizationalPerson)" base-dn="ou=GlobalSales,o=insuranceSales">
          <!--1 or more repetitions:-->
          <primary-link primary-attribute="cn" secondary-attribute="commonname"/>
          <primary-link primary-attribute="sn" secondary-attribute="surname"/>
        </secondary-ldap>
      </dir:saveContainer>
</soapenv:Body>
Response:
<SOAP-ENV:Body>
      <saveContainerResponse container-id="1" xmlns="http://directory.api.de.bpm.tibco.com"/>
</SOAP-ENV:Body>

The response simply returns the ID of the newly-created (or updated) LDAP container.

The goal of comparing primary with secondary attributes is to ensure that data from the secondary LDAP source is only merged together with the appropriate potential resource from the primary LDAP source.

Where a match cannot be found, or where it is not one-to-one, the potential resource will not have a complete, accurate set of information, and it will be either omitted (where no match is found) or marked as invalid (where the match isn't one-to-one).

For example, if there are several resources with the same last name, you need to map more than just the last name; maybe mapping first name too will be enough, or maybe you need to map more attributes (because there may be multiple resources in the secondary LDAP source with the same first and last name — it would not know which to include). Maybe there are other types of data, such as an employee ID that would work better and would avoid inconsistencies in data entry (typos, nicknames, abbreviations, and so on).

You can get the LDAP attributes and their values to use in the primary-attribute and secondary-attribute attributes using the listAttributeNames operation.

Note: If you choose attributes that contain names, always be aware that there may be differences in the way those names were entered in the different LDAP sources, for example, Bob vs. Robert, Mike vs. Michael, or simple misspellings. Things like employee numbers tend to make good attributes to map.