Using an LDAP Attribute Store in AD FS

Key takeaways

• Attribute stores let AD FS enrich tokens with data from AD LDS, other LDAP directories, SQL or custom code.
• The LDAP store's connection string is an LDAP URL; the AD FS service identity needs read permission on the target container.
• Claim rules call the store with issue(store = ..., types = ..., query = ..., param = ...).

Active Directory Federation Services issues claims about users, and by default it reads them from the Active Directory it is joined to. Sometimes the attribute an application needs lives elsewhere: a customer number in AD LDS, a license level in a separate LDAP directory used by a product team, partner contact data that was never synchronized. An attribute store connects AD FS to that source so claim rules can read from it. The companion article covers the claim rule syntax in detail.

What is an attribute store?

An attribute store is a data source AD FS queries while processing claim rules, to look up values it then issues as claims.

AD FS supports four kinds:

How do I add an LDAP attribute store?

Create it in the AD FS management console or with PowerShell, using an LDAP URL as the connection string, and grant the AD FS service account read access.

1. In AD FS Management, open Attribute Stores and choose Add Attribute Store.
2. Give it a short, stable name, for example Partner LDS. Claim rules reference this name.
3. Choose LDAP as the type and enter the connection string as an LDAP URL (RFC 2255 format) pointing at the server, port and base container.
4. Grant the AD FS service identity (often a group managed service account) read permission on that container. For AD LDS, Microsoft's documentation shows dsacls.exe for this.
5. Repeat on every server in the farm if your setup does not replicate the store configuration, and restart the service if prompted.

PowerShell users can do the same with Add-AdfsAttributeStore, passing the name, the store type and a configuration hashtable with the connection.

How do I use the store in a claim rule?

Write a custom rule that issues claims from the store, passing a value from an incoming claim as the query parameter.

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
 => issue(store = "Partner LDS",
          types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
                   "http://example.com/claims/customernumber"),
          query = "(&(objectClass=user)(uid={0}));mail,customerNumber",
          param = regexreplace(c.Value, "^.*\\", ""));

Reading it from the top: when the user has a Windows account name claim, query the store named Partner LDS with an LDAP filter where {0} is replaced by the account name without the domain prefix, return the mail and customerNumber attributes, and issue them as the two claim types in the same order. The syntax article breaks this down further.

How do I check the result?

Sign in to a test relying party and decode the token AD FS sends.

For SAML relying parties, capture the SAMLResponse with your browser's developer tools and paste it into the SAML Decoder. The attribute table shows whether the new claims arrived and with what names. If the assertion is encrypted for the relying party, test with a relying party trust that does not encrypt, or read the AD FS admin and debug event logs instead.

What goes wrong most often?

Permissions, escaping and multi-valued attributes.

• Access denied in the AD FS event log usually means the service identity cannot read the container.
• Empty results often come from the filter: wrong object class, wrong attribute name, or a domain prefix left in {0}.
• Backslashes must be escaped in claim rule strings, which is why the regex above shows \\.
• Multi-valued attributes produce one claim per value, which some applications do not expect.
• Performance: each rule that calls a store is a lookup on every sign-in. Keep queries indexed and the number of store calls small.

For the bigger picture of where AD FS fits today, see the federation guide and the Microsoft 365 federation article.

Questions

Which directories can an AD FS LDAP attribute store use?

Microsoft's documentation describes AD LDS and other LDAP servers that support Windows Integrated Authentication, with the connection given in LDAP URL format. Test with your specific directory, since authentication support varies.

Can I add the store with PowerShell?

Yes. The AD FS PowerShell module includes Add-AdfsAttributeStore, which takes a name, a store type and a configuration with the connection string. The AD FS management console offers the same through Attribute Stores, Add Attribute Store.

Sources

• Microsoft Learn: The role of attribute stores (AD FS)
• Microsoft Learn: Attribute stores (AD FS 2.0, query format)
• Microsoft Learn: The role of the claim rule language

Tagged: AD FS, LDAP, Microsoft, Federation, SAML