Attribute Stores

Applies To: Active Directory Federation Services (AD FS) 2.0

An attribute store is a pluggable module that the policy process for Active Directory Federation Services (AD FS) 2.0 can query to retrieve claim values. For a list of attribute stores that AD FS 2.0 supports, see The Role of Attribute Stores (https://go.microsoft.com/fwlink/?LinkId=182464) in the AD FS 2.0 Design Guide.

Working with attribute stores

The following sections provide details about working with and connecting to the different types of attribute stores that you can configure for use with AD FS 2.0.

Working with Active Directory or AD DS as an attribute store

When you work with Active Directory or Active Directory Domain Services (AD DS) as an attribute store, no connection string is required. When AD FS 2.0 is installed and configured on a domain-joined computer, the Active Directory user account store for that domain is made available as a selectable attribute store. For more information, see Add an Attribute Store.

Working with LDAP-based attribute stores

When you work with other Lightweight Directory Access Protocol (LDAP)-based attribute stores, you must connect to an LDAP server that supports Windows Integrated Authentication. The LDAP connection string must also be written in the format of an LDAP URL, as described in RFC 2255. The following is an example of an LDAP URL:

ldap://localhost:389;cn=AdfsUsers,o=Microsoft,c=US

This string specifies that an LDAP search is being made against an LDAP server named "localhost" over port 389, and the search is to start from the AdfsUsers base object ("cn=AdfsUsers,o=Microsoft,c=US").

Working with SQL-based attribute stores

When you work with Structured Query Language (SQL)-based attribute stores, you also must configure a connection string. The SQL connection string is written in the standard format for Microsoft SQL Server connection strings, for example:

Server=CONTOSOSRV01;Database=UserAttributes;Integrated Security = True

This string specifies that a SQL server named "CONTOSOSRV01" has a database named "UserAttributes" that is used as the attribute store and that it uses Windows Integrated Authentication for SQL Server security. You can use any valid connection string that works with SQL Server. For more information about connection string rules for SQL, search the developer documentation on the Microsoft Developer Network (MSDN) site for the following SQL client property: System.Data.SqlClient.SqlConnection.ConnectionString.

Transact-SQL query syntax modifications and restrictions

Some syntax changes are necessary when you use the AD FS 2.0 claims language to work with Transact-SQL (T-SQL) queries. The primary consideration is how you must specify parameters when passing them through AD FS 2.0 claims rules to the SQL command interpreter.

The claims rule language of AD FS 2.0 requires the String.Format method, and its placeholder syntax (for example, {0}, {1}, and so on), to be used inside the SQL query for parameter substitution. For example, instead of having a SQL Server query such as the following T-SQL statement:

SELECT Email FROM UserAttributes WHERE UserName = @userName

you would have to modify this query as follows to indicate the correct parameterization:

SELECT Email FROM UserAttributes WHERE UserName = {0}

Similar changes apply when you use stored procedures instead of direct SQL queries. For example, instead of having the following T-SQL execution statement:

EXEC spr_GetUserAttributes @userName = @argument

you would have to execute this stored procedure call as expressed in the following syntax:

EXEC spr_GetUserAttributes @userName = {0}

Other than the modified requirements for using placeholders to pass T-SQL parameters, you can use all other aspects of the T-SQL language as they are provided for and supported in SQL Server.

SELECT Email FROM UserAttributes WHERE UserName = '{0}'

In addition to these modifications, the following additional restrictions apply to T-SQL use in AD FS 2.0 claims rules language.

• The only parameters that can be passed to the T-SQL query can be of type string. This restriction follows from the fact that claim values (which form parameters to the query) are strings.

• The T-SQL query can only return values that are of SQL string types (varchar, nvarchar, char, nchar, text, ntext, varchar(max), nvarchar(max)). This restriction exists because any SQL values that are returned are used as a source of the values of claims, which are always strings. This restriction can require some additional overhead in the T-SQL query path because even simple numeric types, such as integer or bit values, must be converted to valid string types inside the SQL Server query process.

• The T-SQL query can return only one SQL table and not a dataset. This restriction is based on how the T-SQL query result is transformed into claims.

For more information about how custom rules are written to use SQL attribute stores, see The Claim Rule Language.

Working with custom attribute stores

When you work with a custom attribute store, you may also have to configure a connection string. In this situation, you can enter any custom code you like that enables a connection to your custom attribute store. The connection string in this situation is a set of name/value pairs that are interpreted as implemented by the custom attribute store developer.