Real documentation for the Custom Rule Language?

Question

I have a scenario where I want to take an incoming claim value and use that to lookup an AD account by searching for a specific (non-standard) attribute that matches the incoming value. From that account I will extract a handful of attributes to issue as claims downstream. The closest thing I can find in the docs is this example:

c:[Type == "http://test/name"]
=> issue(store = "Enterprise AD Attribute Store",
types = ("http://test/email"),
query = ";mail;{0}",
param = c.Value)

 That's great, but the "doc" doesn't explain the format of the query value so I have no idea what I'm allowed or supposed to put in here. Specifically,  I don't understand from this example what attribute it's trying to match the incoming claim against or how to specify the search attribute.

Has anyone uncovered more complete docs on the rule language or (crossing fingers!) an example of something close to what I am trying to do?

TIA
Dave

Answer 1

We will update the documentation. Meanwhile, here is some information below from a document that is in progress.

The Active directory attribute store is used to query Active directories in the enterprise. There is a single instance of this attribute store that is automatically created when AD FS 2.0 starts.

The Active directory attribute store validates and evaluates the query string passed to it using the QUERY keyword. This attribute store recognizes the following format of query

QUERY = <QUERY_FILTER>;<ATTRIBUTES>;<DOMAIN_NAME>\<USERNAME>

Thus the QUERY has three parts separated by two semi-colons.

The QUERY_FILTER is the query string that is executed against the directory to narrow down the directory objects. The ATTRIBUTES is the comma separated name of attributes to be returned from the filtered directory objects. QUERY_FILTER, ATTRIBUTES, DOMAIN_NAME and USERNAME can have parameter replacement placeholders like {0}, {1} etc which are filled with query parameter values passed to it from the program using the PARAM keyword. The order of substitution of PARAM values is in the order in which they appear in the original attribute store query passed to the attribute store. That is, the first PARAM value mentioned in the query is substituted for placeholder {0}, the second PARAM value is substituted for placeholder {1} and so on. After all parameter substitutions (if applicable), the format of the resulting QUERY_FILTER is as defined in [RFC 2254]. Similarly each attribute name in the comma separated list of attributes follows the format of attribute type name as defined in section [4.2] of [RFC2252]. The DOMAIN_NAME portion of the query is used to identify and locate the domain controller (DC) to connect to for executing the LDAP query. The DOMAIN_NAME is used to locate the DC using methods described in section [7.3.6] of [MS-ADTS].

The attribute store implementation executes an LDAP query using QUERY_FILTER as the query targeted at the AD domain controller and requests the return attributes whose names are available in the ATTRIBUTES string. The wire format of what messages are sent to the LDAP server and what messages are returned back to the caller are documented in the appropriate list of RFC’s referred in [RFC 3377].The QUERY_FILTER portion gets substituted as the value of filter as defined in section [4.5.1 Search Request] in [RFC 2251] for search request message. The ATTRIBUTES portion gets substituted as the value of attributes in section [4.5.1 Search Request] in [RFC 2251] for search request message. Note that section [3.1.1.3] of [MS-ADTS] describes Active directory usage of LDAP and conformance/non-conformance to the various LDAP RFCs.

The AD server returns a LDAP Search Result message with attribute values as defined in section [4.5.2 Search Response] in [RFC 2251]. The attribute store implementation then creates a two dimensional array of strings from the value of attributes returned from the server. There are as many rows in the array as the number of directory objects that were filtered using the QUERY_FILTER and there are as many columns in each row as the number of attributes requested. In other words, each column in the row corresponds to one attribute value as requested in the return attribute list. This two dimensional array of strings is ultimately returned as the result of query execution from the AD attribute store. 

Note that if you don’t specify the QUERY_FILTER, then we use the default filter of samAccountName={0}. In that case, you need to give at least one parameter to the query (using PARAM keyword) to substitute for samAccountName value.

Answer 2

Hi

Sorry to butt in on this. Are you therefore saying that samaccount name is a necessary part of every query? I ask because I get a syntax error when doing the following:

query="streetaddress={0};city;"

But the following works:

query="streetaddress={0};city;domain\username" (d\u being a real domain user)

However, this defeats the purpose of what I am trying to achieve because I don't know who the user is, I am trying to query based on street address.

Kind regards.

Brad

Answer 3

I had a similar situation and what I ended up doing was adding active directory as an LDAP attribute store called "Active Directory LDAP".  My issuance rule then looked like this:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
 => issue(store = "Active Directory LDAP", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/role", http://somecompany.com/identity/claims/department), query = "mail={0};tokenGroups,department", param = c.Value);

In a nutshell, the rule issues role and department claims based on an incoming emailaddress claim.

Hope that helps.

Glenn

Answer 4

Thank you for the claim rule language explanation. Is there any update on when the update will occur?

---

Danny Alvares, Technical Solutions Architect IAM

Answer 5

So,

If the query returns two objects, does that mean that the generated claim will have two claim vales for each issue statement?

 

-Jeremy

Answer 6

Also,

How are multi-valued attributes handled if a two-dimensional array is used as described?

 

-Jeremy