F5 Logo MyF5
Search
  1. MyF5 Home
  2. Knowledge Centers
  3. BIG-IP APM
  4. BIG-IP Access Policy Manager: Authentication and Single Sign-On
  5. LDAP and LDAPS Authentication
Manual Chapter : LDAP and LDAPS Authentication

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0
Manual Chapter
Table of Contents | << Previous Chapter | Next 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

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.

Note: 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.

Note: 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. Since APM does not support AAA load balancing, APM must define each pool member with a different priority group. The priority group number increases automatically with each created pool member.

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.

Task list

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 Policy > AAA Servers > 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. Click Finished.
    The new server displays on the list.
The new LDAPS server displays on the LDAP Server list.

Creating 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 Policy > Access Profiles .
    The Access Profiles List screen opens.
  2. Click Create.
    The New Profile screen opens.
  3. In the Name field, type a name for the access profile.
    Note: An access profile name must be unique among all access profile and any per-request policy names.
  4. From the Profile Type list, select one these options:
    • LTM-APM: Select for a web access management configuration.
    • SSL-VPN: Select to configure network access, portal access, or application access. (Most access policy items are available for this type.)
    • ALL: Select to support LTM-APM and SSL-VPN access types.
    • SSO: Select to configure matching virtual servers for Single Sign-On (SSO).
      Note: No access policy is associated with this type of access profile
    • RDG-RAP: Select to validate connections to hosts behind APM when APM acts as a gateway for RDP clients.
    • SWG - Explicit: Select to configure access using Secure Web Gateway explicit forward proxy.
    • SWG - Transparent: Select to configure access using Secure Web Gateway transparent 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.
      Note: You can edit Identity Service profile properties.
    Note: Depending on licensing, you might not see all of these profile types.
    Additional settings display.
  5. In the Language Settings area, add and remove accepted languages, and set the default language.
    A browser uses the highest priority accepted language. If no browser language matches the accepted languages list, the browser uses the default language.
  6. Click Finished.
The access profile displays in the Access Profiles List. Default-log-setting is assigned to the access profile.

Verifying 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.
Note: Log settings are configured in the Access Policy Event Logs 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 Policy > Access Profiles .
    The Access Profiles List 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.
    Note: 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 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.
    Note: 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 visual policy editor displays.
  6. Click the (+) icon anywhere in the access policy to add a new action item.
    Note: 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 visual policy editor 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
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 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.
Note: 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 the Create button.
    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.
    Note: 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.
    Note: 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.

Testing 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.
Note: 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 Policy > AAA Servers > 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 an access policy branch, click the (+) icon to add an item to the access 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 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 substeps 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 visual policy editor 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.
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.
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.
Table of Contents | << Previous Chapter | Next Chapter >>
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5 Networks, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information