Although Active Directory (AD) username and realm/domain attributes are often sufficient for identifying a user, at times you need even more details of the user. For example, "UserPrincipalName" that contains the user’s domain might represent a forest level realm and not the organization to which the user actually belongs to. In some cases, user’s "objectGUID" is required to represent the user object. In addition, the administrator might configure custom attributes at AD for single sign-on and federation. To be able to get these attributes from AD as part of user authentication gives the flexibility to administrator, to control access protected resources and integrate with systems in the cloud.

In addition, one of the major scenarios this would solve is when multiple servers require unique attributes of user. For instance, server A might require user’s "DistinguishedName" and Server B might require "sAMAccountName".

This article describes a mechanism to extract the user attributes from AD as a part of authentication and use these attributes to shape run time traffic.

Audience  

This article aims at administrators who would like to take special actions based on user properties.

Extracted attributes can be used in a variety of ways, including but not limited to, federation with third parties, single sign-on to custom applications that might rely on user specific property such as "ObjectGUID".

This applies to AAA-TM and Gateway products of NetScaler.

Prerequisite

NetScaler 10.5 54.x onwards.

Extracted Attributes

The following is a screen shot of user properties on AD Attribute Editor. All the attributes specified in the Attribute Editor, including custom attributes, can be extracted.

Active Directory/LDAP Configuration on NetScaler

While this feature does not change the way AD/LDAP profile is configured on NetScaler, it however adds new options/parameters that is specified to extract specific user attributes.

New configuration parameters called attribute1, attribute2, and so on till attribute16 are introduced. These options allow administrator to specify upto 16 user attributes as defined in attribute editor in AD. Based on the configuration, NetScaler will query the AD for these attributes when authenticating the user. After it obtains the attributes, NetScaler stores these attributes in user context/session and makes them available with advanced policy expressions. The following section of this article describes how these attributes can be used in run time traffic.

The following is the example LDAP profile:

add authentication ldapAction <myServer> -serverIP 1.1.1.1 --serverPort 3268 -authTimeout 30 -ldapBase "dc=nsi-test,dc=com" -ldapBindDn Administrator@nsi-test.com -ldapBindDnPassword  secret -encrypted -encryptmethod ENCMTHD_2 -ldapLoginName samaccountname -groupAttrName memberOf -ssoNameAttribute samaccountname –authentication ENABLED –attribute1 ObjectGUID –attribute2 DistinguishedName

In the preceding profile, you are configuring two attributes, attribute1 and attribute2. Attribute1 fetches "ObjectGUID" and attribute2 fetches "DistinguishedName".

In NetScaler GUI, this is configured from, Security > AAA Application Traffic > Policies > Authentication > Basic Policies/Advanced Policies > LDAP.
Note: Advanced authentication policies also have this feature.

Similarly, NetScaler Gateway can be configured at, NetScaler Gateway > Policies > Authentication > LDAP.

The following is a screen shot from AAA Application Traffic module.

Use Extracted Attributes at Runtime

After the user attributes are extracted and stored in user session on NetScaler, these can then be referenced in advanced policy expressions of NetScaler.

A new expression, "http.req.user.attribute(n)" can be used to extract these attributes. In the aforementioned expression, "n" is the index of the attribute that was previously stored.

Based on the LDAP profile configured in the preceding section, to extract "ObjectGUID" of user, "http.req.user.attribute(1)" can be used because "ObjectGUID" is obtained and stored in index 1. Likewise, to extract "DistinguishedName", "http.req.user.attribute(2)" can be used.

Practical Uses of Attributes

Like mentioned in the first section, these attributes clearly locate/identify a user. For example, "distinguishedName" can be used to allow/disallow a user from accessing a particular resource and if a contractor is not allowed to access a finance application, these attributes can be used in authorization policies.

Likewise, these can be used in traffic, rewrite and responder policies as well.

Application Scenarios

Authorization

The following policy can be used to authorize user based on their "DistinguishedName":

Add tm authorization policy <mypolicy> ‘http.req.user.attribute(1).eq(“cn=user1, cn=Users, DC=mytest, DC=com”)’ ALLOW

Traffic policy

The following policy can be used to select a specific traffic profile based on user’s "userPrincipalName", assuming it is extracted and stored as attribute3:

Add tm trafficpolicy <mypol> ‘http.req.user.attribute(3).eq(user1@mytest.com)’ <myaction>

Likewise, rewrite and responder policies can take advantage of these attributes.

Conclusion

All the extracted attributes from different authentication sources (such as, AD, RADIUS, SAML, WebAuthentication) are stored in single namespace. This way, "UserPrincipalName" for AD can be specified differently in AD to the way it can be specified on RADIUS server. Administrator can extract "UserPrincipalName" from respective servers and reference them as attribute1 because of serializing namespaces.

Although this article describes extracting attributes from AD, these attributes can be obtained from SAML or WebAuthentication.

Regardless of the authentication source, attributes can be used at run time to shape user access.
Note: In a two factor setup, if both primary and secondary policies extract and store the same attribute index, the first one is stored and the second is ignored. That is, if a policy in primary cascade extracts attribute1 and another policy in secondary cascade extracts attribute1 again, the value gathered by primary cascade is preserved. To avoid this situation, care must be taken in assigning the attributes to be extracted such that there is no conflict.

Advanced Expression	Return Value
http.req.user.login_name	Returns the user entered logon name.
http.req.user.name	Returns the SSO Name attribute value if configured. Otherwise, it returns user entered logon name.
http.req.user.domain	Returns the Domain Name configured in the Session Profile.
http.req.user.passwd	Returns the user entered password.
http.req.user.attribute(1…16)	Returns the extracted attribute value.

The above mentioned sample code is provided to you as is with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the sample code. In no event should the code be used to support ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Although the copyright in the code belongs to Citrix, any distribution of the sample code should include only your own standard copyright attribution, and not that of Citrix. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the sample code.

This article describes a mechanism to extract user attributes from Active Directory as a part of authentication and use these attributes to shape run time traffic.