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

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0
Manual Chapter

LDAP and LDAPS Authentication

About LDAP and LDAPS authentication

You can use LDAPS in place of LDAP when the authentication messages between the Access Policy Manager and the LDAP server must be secured with encryption. However, there are instances where you will not need LDAPS and the security it provides. For example, authentication traffic happens on the internal side of Access Policy Manager, and might not be subject to observation by unauthorized users. Another example of when not to use LDAPS is when authentication is used on separate VLANs to ensure that the traffic cannot be observed by unauthorized users.
How LDAP works
How LDAP works
LDAPS is achieved by directing LDAP traffic over a virtual server that uses server side SSL to communicate with the LDAP server. Essentially, the system creates an LDAP AAA object that has the address of the virtual server. That virtual server (with server SSL) directs its traffic to a pool, which has as a member that has the address of the LDAP server.
How LDAPS works
How LDAPS works
If using LDAP or RADIUS authentication in such a way that requires multiple authentication requests, then One Time Password will not work (because password usage is reached on the second request).

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 |

About AAA high availability

Using AAA high availability with Access Policy Manager (APM), you can configure multiple authentication servers to process requests, so that if one authentication server goes down or loses connectivity, the others can resume authentication requests, and new sessions can be established, as usual.
Although new authentications fail if the BIG-IP system loses connectivity to the server, existing sessions are unaffected provided that they do not attempt to re-authenticate.
APM supports the following AAA servers for high availability: RADIUS, Active Directory, LDAP, CRLDP, and TACACS+. APM supports high availability by providing the option to create a pool of server connections when you configure the supported type of AAA server.
If you use AAA with pools, such as RADIUS pools or Active Directory pools, APM assigns each pool member with a different number for the pool member's priority group value. APM must define each pool member with a different priority group because AAA load balancing is not used. The priority group number increases automatically with each created pool member. Alternative AAA pool configurations can be defined manually using the full flexibility of Local Traffic Manager (LTM) if high availability is desired.

Task summary for configuring for LDAPS authentication

This task list includes all steps required to set up this configuration. If you are adding LDAPS authentication to an existing access policy, you do not need to create another access profile and the access policy might already include a logon page.

Configuring an LDAPS AAA server in APM

You create an LDAPS AAA server when you need to encrypt authentication messages between Access Policy Manager (APM) and the LDAP server.
  1. Select
    Access
    Authentication
    LDAP
    .
    The LDAP servers screen displays.
  2. Click
    Create
    .
    The New Server properties screen opens.
  3. In the
    Name
     field, type a unique name for the authentication server.
  4. For the
    Server Connection
     setting, select
    Use Pool
     even if you have only one LDAP server.
  5. In the
    Server Pool Name
     field, type a name for the AAA server pool.
  6. Populate the
    Server Addresses
     field by typing the IP address of a pool member and clicking
    Add
    .
    Type the IP address of an external LDAP server. If you have more than one pool member, repeat this step.
  7. For the
    Mode
     setting, select
    LDAPS
    .
  8. In the
    Service Port
     field, retain the default port number for LDAPS,
    636
    , or type the port number for the SSL service on the server.
  9. In the
    Admin DN
     field, type the distinguished name (DN) of the user with administrator rights.
    Type the value in this format:
    CN=administrator,CN=users,DC=sales,DC=mycompany,DC=com
    .
  10. In the
    Admin Password
     field, type the administrative password for the server.
  11. In the
    Verify Admin Password
     field, re-type the administrative password for the server.
  12. From the
    SSL Profile (Server)
     list, select an SSL server profile.
    You can select the default profile, serverssl, if you do not need a custom SSL profile.
    LDAPS is achieved by directing LDAP traffic over a virtual server that uses server-side SSL to communicate with the LDAP server.
  13. Skip the
    Timeout
     field because it does not apply when you select
    Use Pool
    .
  14. Click
    Finished
    .
    The new server displays on the list.
The new LDAPS server displays on the LDAP Server list.

Create an access profile

You create an access profile to provide the access policy configuration for a virtual server that establishes a secured session.
  1. On the Main tab, click
    Access
    Profiles / Policies
    .
    The Access Profiles (Per-Session Policies) screen opens.
  2. Click
    Create
    .
    The New Profile screen opens.
  3. In the
    Name
     field, type a unique name for the access profile.
  4. From the
    Profile Type
     list, select one these options:
    • ALL
      : Select to support LTM-APM and SSL-VPN access types.
    • LTM-APM
      : Select for a web access management configuration.
    • OAuth-Resource Server
      : For configuring APM to act as an OAuth resource server that provides an OAuth authorization layer into an API gateway.
    • RDG-RAP
      : Select to validate connections to hosts behind APM when APM acts as a gateway for RDP clients.
    • SSL-VPN
      : Select to configure network access, portal access, or application access. (Most access policy items are available for this type.)
    • SSO
      : Select to configure matching virtual servers for Single Sign-On (SSO).
      No access policy is associated with this type of access profile
    • SWG - Transparent
      : Select to configure access using Secure Web Gateway transparent forward proxy.
    • SWG - Explicit
      : Select to configure access using Secure Web Gateway explicit forward proxy.
    • System Authentication
      : Select to configure administrator access to the BIG-IP system (when using APM as a pluggable authentication module).
    • Identity Service
      : Used internally to provide identity service for a supported integration. Only APM creates this type of profile.
      You can edit Identity Service profile properties.
    Depending on licensing, you might not see all of these profile types.
    Additional settings display.
  5. From the
    Profile Scope
     list, select one these options to define user scope:
    • Profile
      : Access to resources behind the profile.
    • Virtual Server
      : Access to resources behind the virtual server.
    • Global
      : Access to resources behind any access profile with global scope.
    • Named
      : Access for SSL Orchestrator users to resources behind any access profile with global scope.
    • Public
      : Access to resources that are behind the same access profile when the Named scope has configured the session and is checked based on the value and string configured in the Named scope field.
  6. For the
    Customization Type
    , use the default value
    Modern
    .
  7. In the Language Settings area, add and remove accepted languages, and set the default language.
    If no browser language matches one in the accepted languages list, the browser uses the default language.
  8. Click
    Finished
    .
The access profile displays in the Access Profiles List. Default-log-setting is assigned to the access profile.

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.

Configuring LDAPS authentication

You configure an access policy with an LDAP Auth action to provide LDAP authentication for users.
  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 Logon tab, select
    Logon Page
     and click the
    Add Item
     button.
    The Logon Page Agent properties screen opens.
  5. Make any changes that you require to the logon page properties and click
    Save
    .
    The properties screen closes and the policy displays.
  6. 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.
  7. On the Authentication tab, select
    LDAP Auth
     and click
    Add Item
    .
  8. From the
    Server
     list, select an AAA LDAP server.
    The LDAP Auth action uses SSL connections if you select an LDAP AAA server that is configured for LDAPS.
  9. Specify the
    SearchDN
    , and
    SearchFilter
     settings.
    SearchDN is the base DN from which the search is done.
  10. Click
    Save
    .
    The properties screen closes and the policy displays.
  11. Click
    Apply Access Policy
     to save your configuration.
This creates a basic access policy that collects credentials and uses them to authenticate with an LDAP server over SSL. In practice, an access policy might include additional types of authentication and might also assign ACLS and resources
If you use LDAP Query, Access Policy Manager does not query for the primary group and add it to the
memberOf
 attribute. You must manually look up the attribute
memberOf
 as well as the primary group.

Creating a virtual server for LDAPS

You should have an Access Policy Manager LDAP AAA server configured in LDAPS mode.
You create a virtual server to handle LDAP traffic and to encrypt authentication messages between Access Policy Manager and the LDAP server.
An AAA server does not load-balance. Do not select a local traffic pool for this virtual server.
  1. On the Main tab, click
    Local Traffic
    Virtual Servers
    .
    The Virtual Server List screen opens.
  2. Click
    Create
    .
    The New Virtual Server screen opens.
  3. In the
    Name
     field, type a unique name for the virtual server.
  4. From the
    Configuration
     list, select
    Advanced
    .
  5. In the
    Destination Address
     field, type the IP address for the external LDAP server.
    When you type the IP address for a single host, it is not necessary to append a prefix to the address.
    This IP address must match a server address configured in the LDAP AAA server.
  6. In the
    Service Port
     field, type the port number for the LDAP server.
    The server port (389) is the virtual port used as the external LDAP server's service port.
    The LDAP AAA server uses the external LDAP server's SSL service port.
  7. From the
    SSL Profile (Server)
     list, select
    serverssl
    .
    This ensures the SSL connection between the virtual server and the external LDAP server is in place.
  8. From the
    Source Address Translation
     list, select
    Auto Map
    .
  9. Click
    Finished
    .

Testing LDAPS authentication

Before starting this procedure, make sure that all the appropriate steps were performed to create an LDAPS authentication.
  1. Ensure that LDAP authentication works in your environment.
    An intermediate virtual server should not exist for this verification step.
  2. Create an access policy that uses a AAA object that points directly to the LDAP server.
  3. Add an intermediate virtual server without a server-side SSL profile.
    Using the same access policy that you just created, modify the AAA object to point to a virtual server.
  4. Implement LDAPS by enabling server side SSL, and change the pool member to use port
    636
    .
  5. Review the log messages in Access Policy Manager reports.
  6. Make sure to set the Access Policy log level to
    Debug
    .
    To set log levels, see
    System > Logs > Configurations > Options
    .
  7. Review the log for LDAP messages and locate and confirm that the bind and search operation succeeds.

Test AAA high availability for supported authentication servers

To effectively test that high availability works for your authentication servers, you should have two servers that are accessible, where you can remove one of them from the network.
High availability is supported for these authentication server types only: RADIUS, Active Directory, LDAP, CRLDP, and TACACS+.
If you configured a supported authentication server type to use a pool of connection servers, you can test the configuration using these steps.
  1. Begin a
    tcpdump
     on the Access Policy Manager, using a protocol analyzer, and scanning for packets destined for the specific port for your authentication server.
  2. Log in to the virtual server with both servers active.
  3. Using the
    tcpdump
     records, verify that the requests are being sent to the higher priority server.
  4. Log out of the virtual server.
  5. Disable the higher-priority server.
  6. Log in to the virtual server again.
  7. Verify that the request is being sent to the other server.
  8. Log out again, re-enabling the server, and try one more time to verify that the new requests are being sent to the high priority 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

Importing LDAP user groups

Import user groups from an LDAP server to make them available for assigning resources to an LDAP group. When you configure the LDAP Group Resource Assign access policy item, you can type group names to exactly match those on the LDAP server, or you can select them from the imported list of groups.
  1. Select
    Access
    Authentication
    LDAP
    .
    The LDAP servers screen displays.
  2. Click the name of the server that you want to update.
    The Properties screen displays.
  3. From the menu bar, click
    Groups
    .
  4. From the Groups area of the screen, click
    Update
    .
    After uploading the list, the screen displays the number of groups, the date last updated, and the list of groups.

Assigning resources to an LDAP group

You can select groups from a list that you upload from an LDAP server; alternately, or in addition. you can type group names to exactly match LDAP groups. If you plan to select groups and have not updated the list recently, update it from the Groups screen for the AAA LDAP server before you start.
Use an LDAP Group Resource Assign action to assign resources to one or more groups that are configured on the LDAP server. For every group to which a user belongs, the corresponding resources will be assigned to the session.
  1. On a policy branch, click the
    (+)
     icon to add an item to the policy.
    A popup screen displays actions on tabs, such as General Purpose and Authentication, and provides a search field.
  2. On the Assignment tab, select the
    LDAP Group Resource Assign
     agent, and then click
    Add Item
    .
    The LDAP Group Resource Assign screen opens.
  3. To make a list of groups available, select a server from the
    Server
     list.
    A brief pause occurs while the agent retrieves any groups that were previously uploaded from the LDAP server to the BIG-IP system.
  4. To add an entry, click
    Add entry
    .
    An entry must include at least one group and the resources to be assigned to it. You can add multiple entries.
    A numbered entry displays in the Groups area.
  5. In the Groups area, click the
    edit
     link for the entry that you want to update.
    A popup screen opens to the Groups tab.
  6. If you need to add a group, in the
    New Group
     field, type the name of a group that exists on the server and click
    Add group manually
    .
    When the access policy runs, this action queries the group names using the
    memberOf
     attribute in the directory.
    The group displays in the list on the Groups tab.
  7. Select at least one group.
  8. Repeat these steps for each type of resource that you require.
    The screen displays one tab for each resource type.
    1. Click a tab.
    2. Select the resources that you want to assign to the selected groups.
    Typical resource assignment rules apply. For example, you can assign multiple webtop links to a group, but you can assign only one webtop.
  9. Click the
    Update
     button.
    The
    LDAP Group Resource Assign
     screen opens, and displays the groups and resources in the entry in the Groups table.
  10. Create any additional entries that you require.
  11. Click
    Save
    .
    The properties screen closes and the policy displays.
This configures an LDAP group resource assign action and adds it to the access policy.

LDAP authentication session variables

When the LDAP Auth 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 Auth access policy items and for a logon access policy item.

Session variables for LDAP authentication

Session Variable
Description
session.ldap.last.authresult
Provides the result of the LDAP authentication. The available values are:
  • 0: Failed
  • 1: Passed
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.

UserDN settings in LDAP

The following is an example of a typical UserDN usage for LDAP.
Access Policy Manager attempts to bind with the LDAP server using the supplied DN and user-entered password. If the bind succeeds, that is, authentication succeeds, the user is validated. If the bind fails, the authentication fails. This value is a fully qualified DN of the user with rights to run the query. Specify this value in lowercase and without spaces to ensure compatibility with some specific LDAP servers. The specific content of this string depends on your directory layout.
For example, in an LDAP structure, a typical UserDN for query would be similar to the following string:
cn=%{session.logon.last.username}, cn=users, dc=sales, dc=com.
Access Policy Manager supports using session variables in the
SearchFilter
,
SearchDN
, and
UserDN
 settings.
For example, if you want to use the user’s CN from the user’s SSL certificate as input in one of these fields, you can use the session variable
session.ssl.cert.last.cn
 in place of
session.logon.last.username
.

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