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

The following fields are available on the Retrieve From Directory Server filter configuration screen:

Name:
Enter a name for this filter here.

LDAP Directory:
The Enterprise Gateway will query the LDAP directory selected here for user attributes. To configure an LDAP directory, click the Add/Edit button. Take a look at the LDAP Configuration help page for more information on how to do this. An LDAP connection will be retrieved from a pool of connections at run-time.

Retrieve Unique User Identity

Use this section to select the user whose profile the Enterprise Gateway will look 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 and so this is the most likely attribute to enter in this field. Typically this will contain the Distinguished Name (DName) or username of the authenticated user. The name extracted from the selected message attribute will be 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 in order to locate a specific user profile. Once the appropriate profile has been retrieved, the Enterprise Gateway will extract the specified user attributes from it.

Base Criteria:
The value entered specifies where the Enterprise Gateway should begin searching the LDAP directory. You can enter a property representing the value of a message attribute in this field. The two most likely message attributes to use are the authenticated client's ID and DistinguishedName. The corresponding property values are supplied by default:

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

Search Filter:
This is the name given by the particular LDAP directory to the User class. This will depend 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 will search the node to. The options available are:

  • Object level
  • One level
  • Sub-tree

Select the Unique Result checkbox 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 will retrieve from the user profile. If no attributes are explicitly listed here, the Enterprise Gateway will extract all user attributes. In both cases, the retrieved attributes will be 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. Simply 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 will be generated. If this option is not enabled, all attributes will be merged.
  • If an attribute is configured that does not exist in the repository, no error will be generated.
  • If no attributes are configured, all attributes present for the user will be retrieved.