Manual Chapter :
Active Directory Query
Applies To:
Show VersionsBIG-IP APM
- 17.1.0
Active Directory Query
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 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
returnd nested groups in session variables
The AD Query access policy item returns and stores 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 properties: - Enabled - ThememberOfsession variable contains all groups to which the user belongs. As in the example, this includes group1, group2, group3, and group4.
- Disabled - ThememberOfsession 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.
An attribute with a
single unprintable value
7ecc84a2.session.ad.last.attr.objectSid 58 / 0x01050000000000051500000013fe8e97c03cd5b5ad04e2e255040000
Attributes with multiple
values, both printable and unprintable (binary)
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 |
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 policy 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 granting access to particular resources.
Access Policy Manager (APM) stores the attributes it retrieves in session variables.
- On the Main tab, click.The Access Profiles (Per-Session Policies) screen displays.
- In the Per-Session Policy column, click theEditlink for the access profile you want to configure.The visual policy editor opens the access policy in a separate screen.
- 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.
- On the Authentication tab, selectAD Queryand clickAdd Item.A Properties popup screen opens.
- From theServerlist, select the Active Directory AAA server to query.
- You can also set these options.OptionDescriptionSearchFilterType a search filter. (Otherwise if left empty, the policy uses the default filter, sAMAccountName=%{session.logon.last.username}. As a result, theSearchFilterparameter is populated with the Subject Alternative Name from the current Active Directory session.)Fetch Primary GroupEnable this setting to populate the user's primary group in the session variables. This setting is optional.Cross Domain SupportSpecifies whether AD cross domain authentication support is enabled for AD Auth agent. This setting is optional.Fetch Nested GroupsEnable to populate thememberOfsession variable with user's membership in nested groups in addition to the groups to which the user belongs directly.Access Policy Manager does not query for the primary group and add it to thememberOfattribute. You must manually look up the attributememberOfas well as the primary group.Complexity Check for Password ResetEnable this setting so that APM performs the password policy checks it supports.Max Password Reset Attempts AllowedSelect the number of times to allow a user to try to reset their password.Prompt user to change password before expirationSet (N days) to prompt user to change the password before it expires. The default isnone(disabled). This setting is optional.
- ClickSave.
- ClickApply Access Policyto save your configuration.
This
adds an Active Directory query to the access policy.
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
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. - On the Main tab, click.The Access Profiles (Per-Session Policies) screen displays.
- Click the name of the access profile that you want to edit.The properties screen opens.
- On the menu bar, clickLogs.The access profile log settings display.
- Move log settings between theAvailableandSelectedlists.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 theSelectedlist is empty.
- ClickUpdate.
An access profile is in effect when it is assigned to a virtual server.
Using AD query with IPv6
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.
- 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 enterprise.lab.fp.mynet.com domain-controller win2008.enterprise.lab.fp.mynet.comThe host name is win2008.enterprise.lab.fp.mynet.com in the example.
- 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 bigip2mgmt.lab.fp.mynet.com mgmt-dhcp disabled remote-host { /Common/abc { addr 165.160.15.20 hostname win2008.enterprise.lab.fp.mynet.com } } }
- 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 } } }
- Create a wildcard TCP virtual server with these settings:
- Set theDestination IPsettings to the IPv4 address that was used in step 2.That address is 172.31.54.99 in the example.
- For theService Portsetting, select* All ports.
- In the Configuration area, leave theProtocolsetting at the default,TCP.
- Scroll down to theSource Address Translationsetting and selectAuto Map.
- Scroll down to the Resources area and select the pool that you configured previously from theDefault Poollist.
ltm virtual /Common/bigip2.lab.fp.mynet.com-tcp { destination /Common/172.31.54.99:any ip-protocol tcp mask 255.255.255.255 pool /Common/AD-IPv6-Pool profiles { /Common/tcp { } } source-address-translation automap translate-port disabled vlans-disabled } - Create another similar virtual server, but for UDP traffic. (Set the Protocol setting in the virtual server configuration to UDP).ltm virtual /Common/bigip2.lab.fp.mynet.com-udp { destination /Common/172.31.54.99:any ip-protocol udp mask 255.255.255.255 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 |
---|---|
session.ad.last.queryresult
|
Provides the result of the Active Directory query. The available values are:
|
session.ad.last.errmsg
|
Displays the error message for the last login. If
session.ad.last.queryresult is set to 0, then
session.ad.last.errmsg might be useful for troubleshooting purposes. |
session.ad.last.attr.$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. |
session.ad.last.attr.primarygroup.$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 |
Make sure that your log
level is set to the appropriate level. The default log level is notice . |
Confirm network connectivity |
|
Check the Active Directory server configuration |
Since Active Directory is
sensitive to time settings, use NTP to set the correct time on the
BIG-IP
system. |
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.
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. |