Manual Chapter : LDAP Query

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2
Manual Chapter

About LDAP queries

When running the LDAP Query access policy item, Access Policy Manager (APM) queries an external LDAP server for additional information about the user.

Important: If you use LDAP query, Access Policy Manager does not query for the primary group and add it to the memberOf attribute. You must look up the attribute memberOf, as well as the primary group, manually.

The LDAP Query item does not authenticate user credentials. To authenticate users, use another or an additional authentication item in the access policy.

About nested groups in Active Directory and LDAP queries

A nested group is a group that is a member of another group. For example, group1 is a member of group3 and group4. A user, user1, that belongs to group1 and group2 also belongs to group3 and group4 through nesting.

Whether AD Query and LDAP Query return nested groups in session variables

The AD Query and LDAP Query access policy items return and store the groups to which a user belongs in the memberOf session variable.

The contents of the memberOf session variable differ depending on whether the Fetch Nested Group setting is enabled or disabled in AD Query or LDAP Query properties:

  • Enabled - The memberOf session variable contains all groups to which the user belongs. As in the example, this includes group1, group2, group3, and group4.
  • Disabled - The memberOf session variable contains groups to which the user belongs directly. Based on the example, this would be group1 and group2.

About how APM handles binary values in LDAP attributes

For LDAP, Access Policy Manager (APM) converts an attribute value to hex only if the value contains unprintable characters. If the session variable contains several values, and one or more of those values is unprintable, then APM converts only those particular values to hex.

Case 1:

Handling of attributes with single value: 9302eb80.session.ldap.last.attr.objectGUID 34 / 0xfef232d3039be9409a72bfc60bf2a6d0

Case 2:

Handling of attributes with multiple values (mix of binary and non-binary values):29302eb80.session.ldap.last.attr.memberOf 251 | / CN=printable group,OU=groups,OU=someco,DC=smith, / DC=labt,DC=fp,DC=somelabnet,DC=com | / 0x434e3d756e7072696e7461626c6520c2bdc2a12067726f75702c4f553d67726f7570732c4f553d66352c / 44433d73686572776f6f642c44433d6c6162742c44433d66702c44433d66356e65742c44433d636f6d |

Adding an LDAP query to an access policy

Before you add an LDAP query to an access policy, you must have at least one LDAP AAA server configured. You should also have an access profile that is configured with actions to authenticate the user.
You add an LDAP query to an access policy to get information about a user. APM stores the attributes it retrieves in session variables.
  1. On the Main tab, click Access Policy > Access Profiles. The Access Profiles List screen opens.
  2. In the Access Policy column, click the Edit link for the access profile you want to configure. The visual policy editor opens the access policy in a separate screen.
  3. Click the (+) icon anywhere in the access policy to add a new action item. A popup screen opens, listing predefined actions on tabs such as General Purpose, Authentication, and so on.
  4. On the Authentication tab, select LDAP Query and click Add Item.
  5. From the Server list, select an AAA LDAP server. An LDAP Query uses SSL connections when you select an LDAP AAA server that is configured for LDAPS.
  6. Specify the SearchDN, and SearchFilter settings. SearchDN is the base DN from which the search is done.
  7. Click Save. The properties screen closes and the visual policy editor displays.
  8. Click Apply Access Policy to save your configuration.
This adds an LDAP Query to an existing access policy.

Example of LDAP auth and query default rules

In this example, after successful authentication, the system retrieves a user group using an LDAP query. Resources are assigned to users and users are directed to a webtop if the user group has access to the network access resources.

In this figure, the default branch rule for LDAP query was changed to check for a specific user group attribute.

Example of an access policy for LDAP auth query Example of an access policy for LDAP auth query

Session variables in LDAP query properties

You can use session variables to configure properties for the LDAP query access policy item. The properties are listed in the table.

Property Example value Description
SearchFilter (sAMAccountName=%{session.logon.last.username}) Populates the SearchFilter parameter with the username from the current session.
UserDN cn=%{session.logon.last.username}, cn=users, dc=sales, dc=com. A typical UserDN for query in an LDAP structure.
SearchDN session.ssl.cert.last.cn Uses the user CN from the SSL certificate. Useful as a value for any property in this table.

LDAP query session variables

When the LDAP Query access policy item runs, it populates session variables which are then available for use in access policy rules. The tables list the session variables for the LDAP query access policy item and for a logon access policy item.

Session variables for LDAP query

Session Variable Description
session.ldap.last.queryresult Provides the result of the LDAP query. The available values are:
  • 0: Failed
  • 1: Passed
session.ldap.last.attr.$attr_name $attr_name is a value that represents the user's attributes received during LDAP/query. Each attribute is converted to separate session variables.
session.ldap.last.errmsg Useful for troubleshooting, and contains the last error message generated for LDAP, for example aad2a221.ldap.last.errmsg.

Common session variables

Session Variable Description
session.logon.last.username Provides user credentials. The username string is stored after encrypting, using the system's client key.
session.logon.last.password Provides user credentials. The password string is stored after encrypting, using the system's client key.

LDAP authentication and query troubleshooting tips

You might run into problems with LDAP authentication and query in some instances. Follow these tips to try to resolve any issues you might encounter.

LDAP auth and query troubleshooting

Possible error messages Possible explanations and corrective actions
LDAP auth failed
  • User name or password does not match records.
  • No LDAP server is associated with the LDAP Auth agent.
  • The target LDAP server host/port information associated with the LDAP Auth agent might be invalid.
  • The target LDAP service might be not accessible.
LDAP query failed
  • The specified administrative credential is incorrect.
  • If no administrative credential is specified, then the user name or password does not match.
  • No LDAP server is associated with the LDAP query agent.
  • The target LDAP server host/port information associated with the LDAP query agent might be invalid.
  • The target LDAP service might be not accessible.
  • If the LDAP query is successfully, then check whether the LDAP query Rules are properly configured.

Additional troubleshooting tips for LDAP authentication

You should Steps to take
Check that your access policy is attempting to perform authentication
  • Refer to the message boxes in your access policy to display information on what the access policy is attempting to do.
  • Refer to/var/log/apm to view authentication attempts by the access policy.
Note: Make sure that your log level is set to the appropriate level. The default log level is notice
Confirm network connectivity
  • Access the Access Policy Manager through the command line interface and check your connectivity by pinging the LDAP server using the host entry in the AAA Server box.
  • Confirm that the LDAP port 389 is not blocked between the Access Policy Manager and the LDAP server.
Check the LDAP server configuration
  • Verify that the administrative credentials are correct on the LDAP server, and that they match the credentials used by the AAA entry.
Note: A good test is to use full administrative credentials with all rights. If that works, you can use less powerful credentials for verification.
Capture a TCP dump
  • Take a TCP dump from the Access Policy Manager when authentication attempts are made. For example, %tcpdump-i 1.1 -s /tmp/dump. You must first determine what interface the self-IP is on. These TCP dumps indicate activities between the Access Policy Manager and the authentication server.
  • Run the authentication test. After authentication fails, stop the TCP dump, and download the TCP dump to a client system, and use an analyzer to troubleshoot.
Important: If you decide to escalate the issue to customer support, you must provide a capture of the TCP dump when you encounter authentication issues that you cannot otherwise resolve on your own.