F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP Access Policy Manager: Authentication Methods
  3. LDAP Query
Manual Chapter : LDAP Query

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 16.0.1, 16.0.0
Manual Chapter

LDAP Query

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.
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 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.
An attribute with a single unprintable value
9302eb80.session.ldap.last.attr.objectGUID 34 /
0xfef232d3039be9409a72bfc60bf2a6d0
Attribute with multiple values, both printable and unprintable (binary)
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. Access Policy Manager (APM) stores the attributes it retrieves in session variables.
  1. On the Main tab, click
    Access
    Profiles / Policies
    .
    The Access Profiles (Per-Session Policies) screen opens.
  2. In the Per-Session 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 item.
    Only an applicable subset of access policy items is available for selection in the visual policy editor for any access profile type.
    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. From the
    Show Extended Error
     list, specify whether to display comprehensive error messages generated by the authentication server on the user's logon page. This setting is intended only for use in testing, in a production or debugging environment. If enabled in a live environment, your system might be vulnerable to malicious attacks. When disabled, displays non-comprehensive error messages generated by the authentication server on the user's logon page.
  8. Specify how to fetch groups from the
    Fetch groups to which the user or group belong
     list.
    • None
      : Do not fetch groups.
    • Direct
      : Fetch only those groups to which the user or group belong directly.
    • All
      : Fetch groups to which the user or group belong directly; then fetch all groups that are nested under those groups. For example, if the user belongs to Group 1 and Group 2, and Group 1 is a member of Group 3 and Group 4, selecting All associates all four groups to the user. Alternatively, if the group is Group 1, selecting All associates Group 3 and Group 4 to Group 1.
  9. Specifies how to fetch users that are members of the group from the
    Fetch users that belong to the group
     list.
    • None
      : Do not fetch groups.
    • Direct
      : Fetch only those users that belong to the group directly.
    • All
      : Fetch users that belong to the group directly and, if other groups are nested under the group, fetch users that belong to those groups also. For example, if the group (for example, Group 1) is a member of Group 3 and Group 4, selecting All associates the members (users) of all three groups to the group.
  10. Click
    Save
    .
    The properties screen closes and the policy displays.
  11. Click
    Apply Access Policy
     to save your configuration.
This adds an LDAP Query to an existing access policy.

Verify log settings for the access profile

Confirm that the correct log settings are selected for the access profile to ensure that events are logged as you intend.
Log settings are configured in the
Access
Overview
Event Log
Settings
area of the product. They enable and disable logging for access system and URL request filtering events. Log settings also specify log publishers that send log messages to specified destinations.
  1. On the Main tab, click
    Access
    Profiles / Policies
    .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click the name of the access profile that you want to edit.
    The properties screen opens.
  3. On the menu bar, click
    Logs
    .
    The access profile log settings display.
  4. Move log settings between the
    Available
     and
    Selected
     lists.
    You can assign up to three log settings that enable access system logging to an access profile. You can assign additional log settings to an access profile provided that they enable logging for URl request logging only.
    Logging is disabled when the
    Selected
     list is empty.
  5. Click
    Update
    .
An access profile is in effect when it is assigned to a virtual server.

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
Contains only a simple error message for the last error generated for LDAP.
session.ldap.last.errmsgext
Useful for troubleshooting. At any log level, contains extended error information for the last error message generated for LDAP.

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.
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.
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.
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 tcpdump
Use the tcpdump utility on the BIG-IP system to record activities between Access Policy Manager and the authentication server when authentication attempts are made.
  1. Type a command to start the tcpdump utility. For example, type
    tcpdump -s0 -i
    1.1
     -w
    /var/tmp/ldap-test.pcap
     host
    10.10.10.10
     where
    1.1
     is an interface number,
    /var/tmp/ldap-test.pcap
     is the path and filename for the output binary file, and
    10.10.10.10
     is the IP address for the authentication server.
    For tcpdump utility syntax, refer to SOL411: Overview of packet tracing with the tcpdump utility on the AskF5 web site located at
    support.f5.com
    .
  2. Run the authentication test.
  3. After authentication fails, stop the tcpdump utility, download the result to a client system, and use an analyzer to troubleshoot.
If you decide to escalate the issue to customer support, you must provide a capture of the tcpdump when you encounter authentication issues that you cannot otherwise resolve on your own.
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information