Details of our New LDAP Attribute Store for ADFS


The other day, I announced our new LDAP Attribute Store. In that post, I explained how it is not limited to LDAP directory servers that support Integrated Windows Authentication (IWA) like the one that ships with ADFS. I also summarized our new attribute store's features which include the ability to configure a default scope and search base and to override those on a per-rule-basis. In this post, I'll go into a bit more detail about the query syntax of our new store and show some examples of how this can be helpful.

Query Syntax

Every rule that uses the Twobo LDAP Attribute Store must include a query string. This input specifies how to search the LDAP server and what should be returned. This query string will contain two, three, or four distinct parts separated by a back-slash (\). The form is thus:

FILTER + '\' + ATTRIBUTES [ + '\' BASE [ + '\' SCOPE ]]

These parts have the following meanings:

  • FILTER: The first part of the query string is an LDAP filter with optional parameter placeholders. This could be a simple search (e.g., cn={0}) or it could be a complicated expression (e.g., (&(objectClass=person)(cn={0}))).

NOTE: The {0} in these examples is a parameter replacement placeholders as used with other attribute stores. The value is taken from the query parameter that is passed to the rule with the Param keyword.

  • ATTRIBUTES: The second portion of the query string is a comma-separated list of attributes from the LDAP object identified by the filter which should be used as the values for the output claims. The number and order of the attributes specified in the query string must exactly match that of the output claims.
  • BASE: The third part of the query string, if included, will be the base of the search that is performed. This will override any configured default for the attribute store instance, but only for that particular rule.
  • SCOPE: The fourth portion of the query string, if included, will be the scope of the search that is performed, overriding the configured default for the attribute store instance.

Overriding the Default Search Location

When you add the attribute store in ADFS, you have to configure the default search location. You can also specify the search scope.

Attribute Store Settings in ADFS

Interestingly, these defaults are for a particular instance of the Twobo LDAP Attribute Store, and multiple instances of the store can be configured with different defaults. This means that separate instances can be used in claims rules as needed. For example, suppose you define the first instance, Employees, with a default search location of ou=Employees,dc=contoso,dc=com and another instance, Contractors, with a default search location of ou=Contractors,dc=contoso,cn=com. When you define claims issuance rules, you can use these to search different locations in your LDAP directory. For instance, you may have a rule like this to query employees:

c:[Type == "..."] =>
    issue(Store = "Employees", ... );

A query for contractors might require a similar rule, but use the other instance of the attribute store, like this:

c:[Type == "..."] =>
    issue(Store = "Contractors", ... );

This is helpful, but it requires separate instances of the attribute store. This is OK if you you frequently need to query for attributes from these different LDAP containers. If this is an infrequent need, however, it is heavy-handed and adds extra operational overhead. What you could do instead using our attribute store is reuse a single instance and override the search location in the rule itself. If you define the default search base of the store to look in the Employees OU but need to query the Contractors OU for a particular rule, you can do so in a rule like this:

c:[Type == "..."] =>
    issue(Store = "Employees",
        Types = (""),
        Query = "uid={0}\mail\ou=Contractors,dc=contoso,cn=com",
        Param = c.Value);

In this example, the attribute store is not querying the configured container, but rather the one provided in the rule.

Overriding the Default Search Scope

In the same way that the base of a search can be overridden for a particular rule, the scope of the search can also be specified on a per-rule basis. This is done using the four-part syntax. The accepted values are Base, OneLevel, and Subtree and have the normal meanings as used in LDAP. For an explanation of what those meanings are, refer to the adjacent diagram and this article on the LDAP search components.

NOTE: The third portion of the rule -- the base -- does not have to be provided in order to override the scope in the fourth part of the query string. If the configured default base is desired but the scope should be overridden, simply omit an overriding base (e.g., uid={0}\mail\\OneLevel).

An example of a rule that uses the four-part query syntax is shown in the following listing:

c:[Type == "..."] =>
    issue(Store = "...",
        Types = (""),
        Query = "uid={0}\mail\ou=Users,dc=contoso,cn=com\Subtree",
        Param = c.Value);


The Twobo LDAP Attribute Store for ADFS supports other authentication mechanisms besides IWA. From this post, you can see that it also provides a richer query syntax than the stock LDAP attribute store. This makes it easier to find your data after authenticating. These capabilities combined make it an ideal choice when using LDAP directories with ADFS that do not support IWA. If you would like to explore how our attribute store can be used in your ADFS setup, please feel free to contact us.