Contents
The API 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 represented as a list of search results. Each element of the list represents a list of multi-valued attributes returned from the directory server.
Configure the following field:
Name:
Enter an appropriate name for this filter.
Configure the following fields on the Database tab:
LDAP Directory:
The API Gateway queries the selected Lightweight Directory Access Protocol (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 Configuring LDAP Directories.
The Retrieve Unique User Identity section enables you to select the user whose profile the API 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 Selector Expression:
Select this option if the user ID is stored in a message attribute, and specify
the selector expression used to obtain its value at runtime (for example,
${authentication.subject.id}
). A user's credentials are stored in the
authentication.subject.id
message attribute after authenticating to the
API 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 specified message attribute is used to query the directory
server. For more details on selector expressions, see Selecting Configuration Values at Runtime.
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
API 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.
The Retrieve Attributes section instructs the API Gateway to search the LDAP tree to locate a specific user profile. When the appropriate profile is retrieved, the API Gateway extracts the specified user attributes.
Base Criteria:
This value specifies where the API Gateway should begin searching the LDAP directory. You can enter a selector 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 selector values are available in the drop-down list:
-
${authentication.subject.id}
-
${authentication.subject.dname}
However, you can enter selectors representing other message attributes using the same syntax. For more details on selectors, see Selecting Configuration Values at Runtime.
Search Filter:
This is the name given by the particular LDAP directory to the User
class. This depends on the type of LDAP directory configured. You can also use a selector
to represent the value of a message attribute. For example, you can use the
user.role
attribute to store the user class. The syntax for using
the selector representing this attribute is as follows:
(objectclass=${user.role})
Search Scope:
If the API Gateway retrieves a user profile node from the LDAP tree, the option selected here dictates the level that the API Gateway searches the node to. The available options are:
-
Object level
-
One level
-
Sub-tree
Select the Unique Result option to force the API 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 the API Gateway
retrieves from the user profile. If no attributes are listed, the API Gateway
extracts all user attributes. In both cases, retrieved attributes are set to
the attribute.lookup.list
message attribute. Click
Add to add the name of an attribute to extract from the
returned user profile. Enter the attribute name to extract from the profile
in the Attribute Name field of the Attribute
Lookup dialog.
Important | |
---|---|
|
Configure the following fields on the Advanced tab:
Enable legacy attribute naming for retrieved attributes:
Specifies whether to enable legacy naming of retrieved message attributes (unselected by default). Prior to version 7.1, retrieved attributes were stored in message attributes in the following format:
user.<retrieved_attribute_name>
For example, ${user.email}
, ${user.role}
, and so on. If
the retrieved attribute was multi-valued, you would access the values using
${user.email.1}
or ${user.email.2}
, and so on. In version 7.1
and later, by default, you can query for multi-valued retrieved attributes using an array
syntax (for example, ${user.email[0]}
or ${user.email[1]}
, and
so on). Select this setting if you wish to use the legacy format for attribute naming instead.
Example Output when Selected
The following table shows the output attribute format when legacy attribute naming is selected:
Prefix for message attribute name (optional) | Output attribute format (when attribute name is memberOf) |
---|---|
user (default)
|
|
None |
|
Example Output when Unselected
The following table shows the output attribute format when legacy attribute naming is unselected by default:
Prefix for message attribute name (mandatory) | Output attribute format (when attribute name is user.memberOf) |
---|---|
user (default)
|
|
Prefix for message attribute names:
You can specify an optional prefix for message attribute names. The default prefix is
user.
. For more details, see Enable legacy attribute naming for
retrieved attributes.