Retrieve Attributes from Directory Server

Contents

Overview

The Enterprise Gateway can leverage an existing directory server by querying it for user profile data. The Retrieve from Directory Server filter can lookup a user, retrieve that user's attributes, and set them to the attribute.lookup.list message attribute, which stores a map of name-value pairs.

General Configuration

You can configure the following fields on the Retrieve From Directory Server filter configuration screen:

Name:
Enter an appropriate name for this filter.

LDAP Directory:
The Enterprise Gateway queries the selected LDAP directory for user attributes. An LDAP connection is retrieved from a pool of connections at runtime. Click the button on the right to select the LDAP directory to query. If you wish to use an existing LDAP directory, (for example, Sample Active Directory Connection), you can select it in the tree. To add an LDAP directory, right-click the LDAP Connections tree node, and select Add an LDAP Connection.

Alternatively, you can add LDAP connections under the External Connections node in the Policy Studio tree view. For more details on how to configure LDAP connections, see the topic on Configuring LDAP Directories.

Retrieve Unique User Identity

Use this section to select the user whose profile the Enterprise Gateway looks up in the directory server. The user ID can be taken from a message attribute or looked up from an LDAP directory.

From Message Attribute:
Select this option if the user ID is stored in a message attribute. A user's credentials are stored in the authentication.subject.id message attribute after authenticating to the Enterprise Gateway, so this is the most likely attribute to enter in this field. Typically, this contains the Distinguished Name (DName) or username of the authenticated user. The name extracted from the selected message attribute is used to query the directory server.

From LDAP Search:
In cases where you have not already obtained the user's identity and the authentication.subject.id attribute has not been pre-populated by a prior authentication filter, you must configure the Enterprise Gateway to retrieve the user's identity from an LDAP search. Click the Configure Directory Search button to configure the search criteria to use to retrieve the user's unique DName from the LDAP repository.

Retrieve Attributes

This section instructs the Enterprise Gateway to search the LDAP tree according to certain conditions to locate a specific user profile. When the appropriate profile is retrieved, the Enterprise Gateway extracts the specified user attributes from it.

Base Criteria:
This value specifies where the Enterprise Gateway should begin searching the LDAP directory. You can enter a property representing the value of a message attribute, which is expanded at runtime. The two most likely message attributes to specify are the authenticated user's ID and Distinguished Name. The corresponding property values are available in the drop-down list:

  • ${authentication.subject.id}
  • ${authentication.subject.dname}

However, you can also enter properties representing other message attributes using the same syntax.

Search Filter:
This is the name given by the particular LDAP directory to the User class. This depends on the type of LDAP directory that is configured. You can also use properties to represent the value of a message attribute. For example, the user.role attribute can be used to store the user class. The syntax for using the property representing this attribute is as follows:

  • (objectclass=${user.role})

Search Scope:
If the Enterprise Gateway retrieves a user profile node from the LDAP tree, the option selected here dictates the level that the Enterprise Gateway searches the node to. The available options are:

  • Object level
  • One level
  • Sub-tree

Select the Unique Result option to force the Enterprise Gateway to retrieve a unique user profile from the LDAP directory. This is useful in cases where the LDAP search has returned several profiles.

The Attribute Name table lists the attributes that the Enterprise Gateway retrieves from the user profile. If no attributes are listed, the Enterprise Gateway extracts all user attributes. In both cases, the retrieved attributes are set to the attribute.lookup.list message attribute.

Click the Add button to add the name of an attribute to extract from the returned user profile. Enter the name of the attribute to extract from the profile in the Attribute Name field of the Attribute Lookup dialog.

Important Note:
It is important to note the following:

  • If the search returns results for more that one user, and the Unique Result option is enabled, an error is generated. If this option is not enabled, all attributes are merged.
  • If an attribute is configured that does not exist in the repository, no error is generated.
  • If no attributes are configured, all attributes present for the user are retrieved.