Manual Chapter : Active Directory 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

About Active Directory authentication

You can authenticate using Active Directory authentication with Access Policy Manager. We support using Kerberos-based authentication through Active Directory.

About Active Directory password management

Access Policy Manager (APM) supports password management for Active Directory authentication.

How APM supports password reset

The process works in this sequence:

  • Access Policy Manager uses the client's user name and password to authenticate against the Active Directory server on behalf of the client.
  • If the user password on the Active Directory server has expired, Access Policy Manager returns a new logon screen back to the user, requesting that the user change the password.
  • After the user submits the new password, Access Policy Manager attempts to change the password on the Active Directory server. If this is successful, the user's authentication is validated.

If the password change fails, it is likely that the Active Directory server rejected it because the password did not meet the minimum requirements such as password length.

Number of attempts APM provides for password reset

In the AD Auth action, APM provides a Max Password Reset Attempts Allowed property.

Change password option

In the Logon page action, APM provides a Checkbox property in the visual policy editor. You can add the option on the APM logon screen to change the log on password.

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.

About how APM handles binary values in Active Directory attributes

For Active Directory, 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:

7ecc84a2.session.ad.last.attr.objectSid 58 / 0x01050000000000051500000013fe8e97c03cd5b5ad04e2e255040000

Case 2:

Handling of attributes with multiple values (mix of binary and non-binary values):

7ecc84a2.session.ad.last.attr.memberOf 460 | CN=printable group,OU=groups,OU=someco,DC=sherwood,DC=labt,DC=fp,DC=somelabnet,DC=com | 0x434e3d756e7072696e7461626c6520c2bdc2a12067726f75702c4f553d67726f7570732c4f553d66352 | / c44433d73686572776f6f642c44433d6c6162742c44433d66702c44433d66356e65742c44433d636f6d | / CN=Domain Users,CN=Users,DC=smith,DC=labt,DC=fp,DC=somlabnet,DC=com | / CN=CERTSVC_DCOM_ACCESS,CN=Users,DC=smith,DC=labt,DC=fp,DC=somelabnet,DC=com | / CN=Users,CN=Builtin,DC=smith,DC=labt,DC=fp,DC=somelabnet,DC=com |

Task summary for Active Directory authentication

This task list includes all steps required to set up this configuration. If you are adding Active Directory 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 Active Directory AAA server

You configure an Active Directory AAA server in Access Policy Manager (APM) to specify domain controllers and credentials for APM to use for authenticating users.
  1. On the Main tab, click Access Policy > AAA Servers > Active Directory. The Active Directory Servers list screen opens.
  2. Click Create. The New Server properties screen opens.
  3. In the Name field, type a unique name for the authentication server.
  4. In the Domain Name field, type the name of the Windows domain.
  5. For the Server Connection setting, select one of these options:
    • Select Use Pool to set up high availability for the AAA server.
    • Select Direct to set up the AAA server for standalone functionality.
  6. If you selected Direct, type a name in the Domain Controller field.
  7. If you selected Use Pool, configure the pool:
    1. Type a name in the Domain Controller Pool Name field.
    2. Specify the Domain Controllers in the pool by typing the IP address and host name for each, and clicking the Add button.
    3. To monitor the health of the AAA server, you have the option of selecting a health monitor: only the gateway_icmp monitor is appropriate in this case; you can select it from the Server Pool Monitor list.
  8. In the Admin Name field, type a is case-sensitive name for an administrator who has Active Directory administrative permissions. APM uses the information in the Admin Name and Admin Password fields for AD Query. If Active Directory is configured for anonymous queries, you do not need to provide an Admin Name. Otherwise, APM needs an account with sufficient privilege to bind to an Active Directory server, fetch user group information, and fetch Active Directory password policies to support password-related functionality. (APM must fetch password policies, for example, if you select the Prompt user to change password before expiration option in an AD Query action.) If you do not provide Admin account information in this configuration, APM uses the user account to fetch information. This works if the user account has sufficient privilege.
  9. In the Admin Password field, type the administrator password associated with the Domain Name.
  10. In the Verify Admin Password field, retype the administrator password associated with the Domain Name setting.
  11. In the Group Cache Lifetime field, type the number of days. The default lifetime is 30 days.
  12. In the Password Security Object Cache Lifetime field, type the number of days. The default lifetime is 30 days.
  13. From the Kerberos Preauthentication Encryption Type list, select an encryption type. The default is None. If you specify an encryption type, the BIG-IP system includes Kerberos preauthentication data within the first authentication service request (AS-REQ) packet.
  14. In the Timeout field, type a timeout interval (in seconds) for the AAA server. (This setting is optional.)
  15. Click Finished. The new server displays on the list.
This adds the new Active Directory server to the Active Directory Servers 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 Active Directory authentication

Before you configure an access policy use Active Directory authentication, , you must have at least one Active Directory AAA server configured.
You create an access policy like this one to obtain user credentials and use them to authenticate the user against an external Active Directory server before granting access.
  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 AD Auth and click Add Item. A Properties popup screen opens.
  8. From the Server list, select the AAA Active Directory server to use for authentication, and click Save.
  9. You can also set these options.
    Option Description
    Cross Domain Support Specifies whether AD cross domain authentication support is enabled for AD Auth agent.
    Complexity check for Password Reset Specifies whether Access Policy Manager performs a password policy check.
    Note: Enabling this option increases overall authentication traffic significantly because Access Policy Manager must retrieve additional information. Because this option might require administrative privileges, if you enable it you should specify the administrator name and password on the AAA Active Directory server configuration page.
    Show Extended Error When enabled, displays the comprehensive error messages generated by the authentication server to show on the user's Logon page. This setting is intended for use in testing only in a production or debugging environment. If you enable this setting in a live environment, your system might be vulnerable to malicious attacks
    Max Logon Attempts Allowed Specifies the number of user authentication logon attempts to allow.
    Note: To use this access policy for Citrix Receiver client access, set the value to 1.
    Max Password Reset Attempts Allowed Specifies the number of times that Access Policy Manager allows the user to try to change password.
  10. Click Apply Access Policy to save your configuration.
This adds a logon page and Active Directory authentication to the access policy.
To put an access policy into effect, add it to a virtual server.

Creating a virtual server

When creating a virtual server for an access policy, specify that the virtual server is a host virtual server, and not a network 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. For the Destination setting, select Host and in the Address field, type the IP address for the virtual server.
  5. In the Service Port field, type a port number or select a service name from the Service Port list.
  6. From the HTTP Profile list, select http.
  7. If you use server SSL for this connection, from the SSL Profile (Server) list, select a server SSL profile.
  8. If you use client SSL for this profile, from the SSL Profile (Client) list, select a client SSL profile.
  9. In the Access Policy area, from the Access Profile list, select the access profile.
  10. From the Connectivity Profile list, select a connectivity profile. You can select the default connectivity profile, connectivity if you have not defined a specific profile for the traffic that is directed to this virtual server.
  11. Click Finished.
You have configured a host virtual server and associated an access profile with it.

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 access policy using Active Directory authentication and query

This is an example of an access policy with all the associated elements that are needed to authenticate and authorize your users with Active Directory authentication and Active Directory query.

Example of an access policy for AD auth query Example of an access policy for AD auth and query

Active Directory authentication session variables

When the AD 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 Active Directory access policy items and for a logon access policy item.

Session variables for Active Directory authentication

Session Variable Description
session.ad.last.actualdomain AD Auth agent sets this variable to the actual user domain used for successful Active Directory authentication, whether cross-domain support is enabled or disabled.
session.ad.last.authresult Provides the result of the Active Directory authentication. The available values are:
  • 0: Failed
  • 1: Passed
session.ad.last.errmsg Displays the error message for the last login. If session.ad.last.authresultis set to 0, then session.ad.last.errmsg might be useful for troubleshooting purposes.

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.

Active Directory cross-domain support rules

Rules Explanation
Cross-domain support and split domain from username are both enabled. If you enable cross domain support, and enable split domain username at the login page, and then the user enters his user name, such as user@domain.com, Access Policy Manager uses the user@domain.com as the user principal name to authenticate the user against USERNAME.COM domain.
Cross-domain support is enabled but split domain from username is disabled Access Policy Manager handles the user's input as a simple user name and escape "@" and "\" chars. In other words, Access Policy Manager uses user\@userdomain.com@DEFAULTREALM.COM to authenticate the user, where DEFAULTREALM.COM is the domain name that was configured on the AAA AD Server configuration page.
If user does not specify a user's domain Regardless of whether split domain from username option is enabled or disabled, Access Policy Manager uses user@defaultrealm.com to authenticate the user.

Active Directory authentication and query troubleshooting tips

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

Active Directory auth authentication and query troubleshooting

Possible error messages Possible explanations and corrective actions
Domain controller reply did not match expectations.(-1765328237) This error occurs when the principal/domain name does not match the domain controller server's database. For example, if the actual domain is SALES.MYCOMPANY.COM, and the administrator specifies STRESS as the domain, then the krb5.conf file displays the following: default_realm = SALES SALES = { domain controller = (domain controller server) admin = (admin server) So, when the administrator tries to authenticate with useraccount@SALES, the krb5 library notices that the principal name SALES differs from the actual one in the server database.

Additional troubleshooting tips for Active Directory 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 Active Directory server using the host entry in the AAA Server box.
  • Confirm that the Active Directory port (88 or 389) is not blocked between the Access Policy Manager, and the Active Directory server.
Check the Active Directory server configuration
  • Confirm that the Active Directory server name can be resolved to the correct IP address, and that the reverse name resolution (IP address to name) is also possible.
  • Confirm that the Active Directory server and the Access Policy Manager have the correct time setting configured.
Note: Since Active Directory is sensitive to time settings, use NTP to set the correct time on the Access Policy Manager.
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 address 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.

Overview: Using Active Directory Trusted Domains

Active Directory Trusted Domains option in BIG-IP Access Policy Manager (APM) manages Active Directory AAA trusted domains. For enterprises that are service providers, their customers might have their own enterprise network infrastructure. Using APM, the service provider provides access to their customers' networks. To avoid network traffic collisions between two customer networks, the service provider separates each customer using route domains. A route domain is a configuration object that isolates network traffic for a particular application on the network. The service provider uses Active Directory to authenticate their customer users. However, each customer's Active Directory service can contain multiple trusted domains or forests. The service provider can use the Active Directory Trusted Domains option to authenticate users across all trusted domains or forests for a customer.

Configuring an Active Directory Trusted Domain

You must create at least one Active Directory AAA server before you can configure an Active Directory Trusted Domain.
Configure an Active Directory Trusted Domain in Access Policy Manager (APM) to authenticate users in route domains with at least one trusted domain.
  1. On the Main tab, click Access Policy > AAA Servers > Active Directory Trusted Domains. The Active Directory Trusted Domains list screen opens.
  2. Click Create. The Create New Active Directory Trusted Domains screen opens.
  3. In the Name field, type a name for the Active Directory Trusted Domain.
  4. In the Description field, type a description for the Active Directory Trusted Domain.
  5. For the XXX setting, in the Available list, select the Active Directory AAA server that you want to add to the Trusted Domain, and click << to move the Active Directory AAA server into the Selected list.
  6. From the Root list, select a root domain. You use the root domain for an initial authentication request, such as an entry point to an Active Directory forest.
  7. Click OK.
You have now added an Active Directory Trusted Domain to the Active Directory Trusted Domain list.
You can now add the Active Directory Trusted Domain option to either the AD Auth agent or the AD Query agent in the visual policy editor.
Note: You can select a trusted domain only if you enable the Cross Domain support option.