PingDirectory API Reference

Join request control

The proprietary join request control can be included in a search request to indicate that each search result entry may include a corresponding join result control with information from one or more other entries that are in some way related to (for example, "joined with") that search result entry. The control has an OID of 1.3.6.1.4.1.30221.2.5.9, and it takes a value. The following fields may be present in the value-json representation of the value:

  • join-rule: A mandatory JSON object field that provides the primary criteria to use when selecting entries to be joined with each search result entry. This is described in detail below.

  • base-dn-type: A mandatory string field that indicates how the server should determine the base DN to use for joined entries. Only entries matching or below the join base DN (and within the join scope) may be joined with search result entries. This field must have one of the following values:

    • use-search-base-dn : Indicates that the server should use the base DN from the associated search request as the join base DN.

    • use-source-entry-dn: Indicates that the server should use the DN of the associated search result entry as the join base DN.

    • use-custom-base-dn: Indicates that the server should use the specific base DN specified in the base-dn-value field as the join base DN.

  • base-dn-value: An optional string field whose value is the base DN that should be used for joined entries. This field must be present if the base-dn-type value is use-custom-base-dn; otherwise, it must be absent.

  • scope: An optional string field whose value is the scope to use for joined entries. If this is not provided, then the scope from the associated search request will be used. Otherwise, it must have one of the following values (which match the allowed searchScope values in the Directory REST API):

    • baseObject: Indicates that only the entry specified as the join base DN may be joined with the search result entry.

    • singleLevel: Indicates that only entries immediately below the join base DN (but not the join base entry itself, nor any entries more than one level below it) may be joined with the search result entry.

    • wholeSubtree: Indicates that the join base entry or any of its subordinates (to any depth) may be joined with the search result entry.

    • subordinateSubtree: Indicates that any entries below the join base entry (to any depth), but not the join base entry itself, may be joined with the search result entry.

  • alias-dereferencing-behavior: An optional string field whose value is the behavior to use when dereferencing any aliases encountered during join processing. Note that while the LDAP version of the join request control does allow this element to be present, the Ping Identity Directory Server does not support aliases, so it has no purpose and should generally be omitted. However, if a value is provided, then its value must be one of "neverDerefAliases", "derefInSearching", "derefInFindingBaseObj", or "derefAlways".

  • size-limit: An optional integer field that specifies the maximum number of entries that may be joined with any single search result entry. If this is not specified, the size limit from the search request will be used as the join size limit. Note that the server will impose a maximum join size limit of no more than 1000 entries (and possibly smaller than that, based on resource limits in place for the requester), so the server may use a smaller size limit than the one requested by the client.

  • filter: An optional string field whose value is the string representation of a search filter that entries will be required to match in order to be joined with a search result entry.

  • attributes: An optional array field whose values are strings that represent the names of the attributes that should be included in joined entries. If this field is not provided, or if its value is an empty array, then the server behaves as if all user attributes and no operational attributes had been requested.

  • require-match: A mandatory Boolean field that indicates whether a search result entry will be required to be joined with one or more other entries to be included in the set of search results. If this field has a value of true, then a search result entry that is not joined with any other entries will not be returned to the client. If this field has a value of false, then search result entries that match the original search request criteria may be returned even if they are not joined with any other entries.

  • nested-join: An optional JSON object field that may be used to specify nested join criteria, in which each joined entry may itself be joined with other entries. If this is specified, then the fields of this JSON object are the same as those that may be used in the value-json element (including another nested-join field if desired).

The main criteria used to identify entries that should be joined with each search result entry is specified using the join rule. The supported join rule types are:

  • DN Join: Indicates that the search result entry includes an attribute whose values are the DNs of the entries to be joined with it. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For a DN join, the value must be "dn".

    • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry whose values are the DNs of the entries to be joined with that entry.

  • Reverse DN Join: Indicates that the entries to be joined with a search result entry include an attribute in which one of the values is the DN of the search result entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For a reverse DN join, the value must be "reverse-dn".

    • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined in which one of the values is the DN of the source entry.

  • Equality Join: Indicates that the entries to be joined with a search result entry must include an attribute with a value that matches the value of a corresponding attribute in the source entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For an equality join, the value must be "equality".

    • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry that must have at least one value that matches a value in the target attribute.

    • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined that must match at least one value from the source attribute.

    • match-all: A mandatory Boolean field that indicates how to handle multi-valued source attributes. If this field has a value of true, then an entry will be joined with the source entry only if the target attribute contains all of the values of the source attribute. If it has a value of false, then an entry may be joined with the source entry as long as at least one of the values of the source attribute is present in the target attribute.

  • Contains Join: Indicates that the entries to be joined with a search result entry must include an attribute with a value that contains (or is equal to) a value from a corresponding attribute in the source entry. That is, at least one value from an attribute in the source entry must be a substring of a value of a specified attribute in the target entry. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For a contains join, the value must be "contains".

    • source-attribute: A mandatory string field whose value is the name of the attribute in the source entry that must have at least one value that matches or is a substring of a value in the target attribute.

    • target-attribute: A mandatory string field whose value is the name of the attribute in the entries to be joined that must contain at least one value that matches or contains a substring that matches a value from the source entry.

    • match-all: A mandatory Boolean field that indicates how to handle multi-valued source attributes. If this field has a value of true, then an entry will be joined with the source entry only if the target attribute contains has values in which all of the source attribute values are present as substrings. If this field is absent, or if it is present with a value of false, then an entry may be joined with the source entry as long as at least one of the values of the target attribute contains at least one of the values of the source attribute as a substring.

  • AND Join: Indicates that the entries to be joined with a search result entry must match multiple sets of nested join rules. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For an AND join, the value must be "and".

    • rules: A mandatory, non-empty array field whose values are JSON objects that represent the nested join rules that will all be required to match a given entry for that entry to be joined with the source entry.

  • OR Join: Indicates that the entries to be joined with a search result entry must match at least one of a given set of nested join rules. If this type of join is to be used, then the join-rule JSON object may include the following fields:

    • type: A mandatory string field that indicates the join rule type. For an OR join, the value must be "or".

    • rules: A mandatory, non-empty array field whose values are JSON objects that represent the nested join rules of which at least one must match a given entry for that entry to be joined with the source entry.

The following sample shows the JSON encoding for the control:

{
    "oid":"1.3.6.1.4.1.30221.2.5.9",
    "control-name":"Join Request Control",
    "criticality":false,
    "value-json": {
        "join-rule": {
            "type":"dn",
            "attribute":"manager"
        },
        "base-dn-type":"use-custom-base-dn",
        "base-dn-value":"ou=People,dc=example,dc=com",
        "scope":"wholeSubtree",
        "size-limit":10,
        "attributes": [
            "givenName",
            "sn",
            "cn",
            "mail"
        ],
        "require-match":false
    }
}