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

  • 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
Table of Contents | << Previous Chapter | Next Chapter >>

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.

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 |

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. Type a name for the access profile.
  4. From the Profile Type list, select one:
    • APM-LTM - Select for a web access management configuration.
    • SSO - Select only when you do not need to configure an access policy.
    • 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.
    • SSL-VPN - Select for other types of access, such as network access, portal access, application access. (Most access policy items are available for this type.)
    • ALL - Select for any type of access.
    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.
This creates an access profile with a default access policy.

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. 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. 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. For the Destination setting in the Address field, type the IP address for the external LDAP server. 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

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