Manual Chapter : Active Directory Query

Applies To:

Show Versions Show Versions


  • 11.5.1
Manual Chapter

About Active Directory queries

When running the AD Query access policy item, Access Policy Manager (APM) queries an external Active Directory server for additional information about the user. The AD Query item looks up the attribute memberOf to fetch the groups to which a user belongs and provides an additional option to fetch the primary group.

The AD Query item does not authenticate user credentials. To authenticate users, use another or an additional authentication item in the access policy.

About nested groups in Active Directory and LDAP queries

A nested group is a group that is a member of another group. For example, group1 is a member of group3 and group4. A user, user1, that belongs to group1 and group2 also belongs to group3 and group4 through nesting.

Whether AD Query and LDAP Query return nested groups in session variables

The AD Query and LDAP Query access policy items return and store the groups to which a user belongs in the memberOf session variable.

The contents of the memberOf session variable differ depending on whether the Fetch Nested Group setting is enabled or disabled in AD Query or LDAP Query properties:

  • Enabled - The memberOf session variable contains all groups to which the user belongs. As in the example, this includes group1, group2, group3, and group4.
  • Disabled - The memberOf session variable contains groups to which the user belongs directly. Based on the example, this would be group1 and group2.

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 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: 58 / 0x01050000000000051500000013fe8e97c03cd5b5ad04e2e255040000

Case 2:

Handling of attributes with multiple values (mix of binary and non-binary values): 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 |

Adding an Active Directory query to an access policy

Before you add an AD query to an access policy, you must have at least one AD AAA server configured. You should also have an access profile that is configured with actions to authenticate the user.
You add an AD query to an access policy to get information about a user; for example, you might want to know whether a user is a member of a group before grancing access to particular particular resources. APM stores the attributes it retrieves in session variables.
  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 Authentication tab, select AD Query and click Add Item. A Properties popup screen opens.
  5. From the Server list, select the Active Directory AAA server to query.
  6. You can also set these options.
    Option Description
    SearchFilter Type a search filter. (Otherwise if left empty, the policy uses the default filter, sAMAccountName=%{session.logon.last.username}. As a result, the SearchFilter parameter is populated with the Subject Alternative Name from the current Active Directory session.)
    Fetch Primary Group Enable this setting to populate the user's primary group in the session variables. This setting is optional.
    Cross Domain Support Specifies whether AD cross domain authentication support is enabled for AD Auth agent. This setting is optional.
    Fetch Nested Groups Enable to populate the memberOf session variable with user's membership in nested groups in addition to the groups to which the user belongs directly.
    Important: 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.
    Complexity Check for Passwork Reset Enable this setting so that APM performs the password policy checks it supports.
    Max Password Reset Attempts Allowed Select the number of times to allow a user to try to reset their password.
    Prompt user to change password before expiration Set (N days) to prompt user to change the password before it expires. The default is none (disabled). This setting is optional.
  7. Click Save.
  8. Click Apply Access Policy to save your configuration.
This adds an Active Directory query to the access policy.

Using AD query with IPv6

When you configure an AD AAA server with an IPv6 address in the Domain Controller setting, an AD query does not work. However, we tested AD query with an IPv6 address using this approach.
  1. In the AD server configuration, use the host name of the DC in the Domain Controller setting. apm aaa active-directory /Common/AD-IPv6 { admin-encrypted-password ".(.5(lEhJfN\\<^FaLGC0Bt8CG0KMfR\\9;coEKdIm=5@32II" admin-name Administrator domain domain-controller The host name is in the example.
  2. Update the system's global setting to include a remote host entry for the DC host name that was used in step 1 and map it to an IPv4 address as shown in this example. sys global-settings { gui-setup disabled hostname mgmt-dhcp disabled remote-host { /Common/abc { addr hostname } } }
  3. Create a pool with the DC IPv6 address as a member as shown in this example. ltm pool /Common/AD-IPv6-Pool { members { /Common/fd00:ffff:ffff:fff1:912e:cdfe:c884:2607.any { address fd00:ffff:ffff:fff1:912e:cdfe:c884:2607 } } }
  4. Create a wildcard TCP virtual server with these settings:
    1. Set the Destination IP settings to the IPv4 address that was used in step 2. That address is in the example.
    2. For the Service Port setting, select * All ports.
    3. In the Configuration area, leave the Protocol setting at the default, TCP.
    4. Scroll down to the Source Address Translation setting and select Auto Map.
    5. Scroll down to the Resources area and select the pool that you configured previously from the Default Pool list.
    ltm virtual /Common/ { destination /Common/ ip-protocol tcp mask pool /Common/AD-IPv6-Pool profiles { /Common/tcp { } } source-address-translation automap translate-port disabled vlans-disabled }
  5. Create another similar virtual server, but for UDP traffic. (Set the Protocol setting in the virtual server configuration to UDP). ltm virtual /Common/ { destination /Common/ ip-protocol udp mask pool /Common/AD-IPv6-Pool profiles { /Common/udp { } } source-address-translation automap translate-port disabled vlans-disabled }

Active Directory query session variables

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

Session variables for Active Directory query

Session Variable Description Provides the result of the Active Directory query. The available values are:
  • 0: Failed
  • 1: Passed Displays the error message for the last login. If is set to 0, then might be useful for troubleshooting purposes.$attr_name $attr_name is a value that represents the user’s attributes received from the Active Directory. Each attribute is converted to separate session variables.$attr_name primarygroup.$attr_name is a value that represents the user’s group attributes received from the Active Directory. Each attribute is converted to separate session variables.

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