Introduction
There have been a ton of requests on the boards for a simplified client side NTLM configuration, so based on Michael Koyfman’s excellent Leveraging BIG-IP APM for seamless client NTLM Authentication, I’ve put together this article to show the very basic requirements for setting up APM client side NTLM authentication.
So why APM client side NTLM? Like Kerberos, NTLM can provide seamless (i.e.. transparent) logon for local clients. It’s arguably not as secure as Kerberos as authentication protocols go, but if you’ve ever worked with Kerberos, you’ll likely appreciate that NTLM is simpler and a bit more flexible. APM’s client side NTLM authentication is also considerably different than the other client side methods that generally include visual policy authentication agents and a AAA configuration. This difference allows client side NTLM to be enabled and disabled per request as needed by Microsoft Exchange and Secure Web Gateway access features. APM’s client side NTLM is controlled by a feature called ECA, or External Client Authentication. Let’s jump right in and look at how ECA is used to configure NTLM. There have been some changes to the way client side NTLM functions between APM versions, so this article will focus on 11.6.
Configuration
Step 1: Create a virtual server
It may seem counter-intuitive to create the virtual server first, but you’ll need it in step 5 below. Nothing fancy here, just create a standard virtual server and assign an HTTP profile and pool. Of course if you’re offloading SSL (which you should be) also include a client SSL profile.
Step 2: Configure system DNS
APM needs to be able to resolve the Active Directory domain controller(s), so you’ll need to specify the DNS for the domain. In the BIG-IP management GUI, navigate to System -> Configuration -> Device -> DNS. In the DNS Lookup Server List section, add the IP address of any AD DNS server(s).
You can do the same in the TM shell as follows:
tmsh modify sys dns name-servers replace-all-with { [IP address of DC DNS server] }
Step 3: Create an Active Directory NTLM machine account
This step creates a computer account in the Active Directory that APM will use to validate the NTLM tokens from clients. This machine account will be used in a pass-through authentication capacity. Please see the following Microsoft article for more information on NTLM Pass-Through Authentication. In the BIG-IP management GUI, navigate to Access Policy -> Access Profiles -> NTLM -> Machine Account. Click the Create button. At a minimum you need an arbitrary profile object name, the name of the computer account to create (it must not already exists), the domain FQDN (the DCs will be resolved via DNS SRV queries), and the credentials of a user with privileges to create computer accounts. To specify a single domain controller, enter that DC’s FQDN into the Domain Controller FQDN field. Click the Join button to proceed.
You can do the same in the TM shell as follows:
tmsh create apm ntlm machine-account [profile object name] domain-fqdn [domain FQDN] machine-account-name [new machine account name] administrator-name [admin name] administrator-password ["admin password"]
If the command is successful you’ll see a new computer account in the Active Directory.
Step 4: Create an NTLM Auth Configuration
Now let’s add that computer account object to an NTLM Auth configuration. In the BIG-IP management GUI, navigate to Access Policy -> Access Profiles -> NTLM -> NTLM Auth Configuration. Click the Create button. Give it an arbitrary object profile name and specify the previously-created machine account name. Add the FQDN for a domain controller to the Domain Controller FQDN List field.
Note: You must add at least one domain controller here. If you don’t specify anything, users will be allowed access without any NTLM token validation. In some APM versions the Domain Controller FQDN List field displays as mandatory and in others optional. In all cases it is absolutely required.
Click the finished button to proceed. You can do the same in the TM shell as follows:
tmsh create apm ntlm ntlm-auth [profile object name] machine-account-name [machine account object name]
Step 5: Enable the ECA profile for a specific virtual server
Unlike the other APM client side authentication methods, there’s no GUI option to enable APM client side NTLM. To do that you need to apply the ECA profile to a virtual via the TM shell.
tmsh modify ltm virtual [virtual server name] profiles add { eca }
Step 6: Create an iRule to enable client side NTLM
This is where all of the magic happens. Create this very simple iRule and apply it to your virtual server:
when HTTP_REQUEST {
ECA::enable
ECA::select select_ntlm:/Common/my-ntlm-machine-auth
}
That’s it. You need to enable ECA and then specify the name of the NTLM Auth configuration object (created in step 4 above). I would also point out here that client side NTLM authentication is a bit different from Kerberos in that ECA is generally going to issue a 401 Unauthorized NTLM challenge on every new request. If this proves to add too much overhead, the following modification to the above iRule will allow NTLM to be processed once at the beginning of the session. The APM session cookie is used thereafter to maintain the session.
when HTTP_REQUEST {
if { [ACCESS::session data get session.ntlm.last.result] eq 1 } {
ECA::disable
} else {
ECA::enable
ECA::select select_ntlm:/Common/my-ntlm-machine-auth
}
}
Step 7: Create an access profile
Create a standard access profile and configure the visual policy like this:
There’s nothing to configure inside the NTLM Auth Result agent so it’s just there to validate the returned session.ntlm.last.result session variable. Add this access profile to the virtual server.
Step 8: Modify the client browser to support NTLM authentication
By default modern browsers do not, for obvious security reasons, send credentials to any web site that asks for them, so you have to explicitly define what sites the browser can send credentials to. For Microsoft Internet Explorer that’s as simple as adding the site to the Local Intranet Sites list. In Internet Explorer, go to Tools -> Internet Options. Open the Security tab, select Local intranet and then click the Sites button. Now click the Advanced button. Add the APM virtual server’s URL here. You can specify the exact URL here (ex. https://ntlm-test.domain.com) or a wildcard (ex. *.domain.com) to cover everything under a given domain.
This should also cover Chrome and Opera running in Windows. For Firefox, navigate to the config URL at about:config and type “trusted” in the Search field. You’ll see a short list of keys with the word “trusted” in them. Double click the “network.automatic-ntlm-auth.trusted-uris” key and add either the full FQDN of a specific APM virtual server (ex. ntlm-test.domain.com) or for an entire domain just the domain component itself (ex. .domain.com).
Testing and Troubleshooting
With your browser(s) configured, go ahead and test. If you get prompted for username and password, NTLM authentication has failed. Probably one of the best first things to do is to open a console (SSH) shell and tail the APM and LTM logs. In many cases the error will be screaming at you from one of these logs.
# cd /var/log # tail –f ltm apm
Here are some possible causes for client side NTLM authentication to fail:
-
Your browser isn’t correctly configured to send credentials to this site: Review the browser’s security configurations. I mentioned earlier that IE’s Local intranet sites list must include the FQDN of the APM virtual server. Make sure you’re indeed using the Local intranet sites list and not one of the other sites lists. There is also another setting in IE that can cause issues. This setting is enabled by default, but you could be in an environment where it has been disabled by policy. Under the Security tab of IE’s Internet Options, click on the “Custom level…” button, scroll all the way to the bottom of that list and look for the “Automatic logon only in Intranet zone” option. This needs to be checked and is the reason why you add the APM virtual server to the Local intranet sites list.
-
You’re not logged in as a domain member and/or your workstation is not domain joined: Check that you’re actually logged into the domain from a domain-joined workstation.
-
APM can’t access the specified domain controller in the NTLM Auth config: You may see messages in the LTM log like “NT_STATUS_INVALID_COMPUTER_NAME”. This is indicating that APM cannot resolve the address of the domain controller specified in the NTLM Auth configuration. If the domain controller just isn’t available, you may see the “NT_STATUS_HOST_UNREACHABLE” error message.
-
NTLM is not enabled or configured correctly in the Active Directory: You may see messages in the APM log like “NT_STATUS_NETWORK_ACCESS_DENIED” or “NT_STATUS_PIPE_NOT_AVAILABLE”. These are indication that there’s probably something wrong on the Windows domain controller side. You may want to take a look at local or domain group policy settings and NTLM event logs.
-
Worst case the NTLM machine account is corrupt: If all else fails, delete and recreate the NTLM machine account. You’ll need to delete it in APM and in the domain. Wait for replication to finish if there are multiple DCs and you’re using the same machine name, or simply use a different machine name.
Let’s now see what that client side NTLM authentication looks like on the wire. For this part I’m going to fire up WireShark and filter on “ntlmssp”
The ECA profile is responsible for generating the 401 Unauthorized response to the client’s initial request. In that 401 response is the WWW-Authenticate header and NTLM challenge. If there’s something wrong you may also see error messages manifest in the Wireshark captures.
Cross-domain Considerations
Client side APM NTLM authentication natively works across domains if the domains are in a forest trust, external two-way trust, or external one-way outgoing trust. For non-trusting domains, since the NTLM Auth config profile is assigned first, there’s no native way to switch between profiles based on something in the client’s NTLM challenge response. If you can identify the clients by some other characteristic, a unique IP subnet for example, that might be an option.
Expanding Possibilities
Now that we have APM client side NTLM humming along, let’s look at some other things you can do with it. A successful client side NTLM authentication will produce a few interesting session values:
-
session.logon.last.username – the APM session variable that contains the logged in username
-
session.logon.last.domain – the APM session variable that contains the domain of the logged in user
-
session.logon.last.machinename – the APM session variable that contains the logged in user’s workstation name
These session variables can be used and evaluated inside the visual policy and in iRules. For example, let’s say you want to do an AD query with the username to see if the user is in a specific AD group:
The ECA profile also creates three other values that can be used in iRules:
-
ECA::status – the authentication status for that individual request. It’s usually either STATUS_SUCCESS or STATUS_ACCESS_DENIED
-
ECA::username – the same information in the username session variable
-
ECA::domainname – the same information in the domain session variable
-
ECA::client_machine_name – the same information in the machine name session variable
Since the ECA profile is also enabled at will, there are some other things you can do with it. One example would be to enable and disable client side NTLM based on the requested URI:
when HTTP_REQUEST {
if { [HTTP::uri] starts_with “/protected_uri” } {
ECA::enable
ECA::select select_ntlm:/Common/my-ntlm-machine-auth
} else {
ECA::disable
}
}
And finally you have two ECA events, ECA_REQUEST_ALLOWED and ECA_REQUEST_DENIED that can be used to trigger specific actions on successful authentication or denied logon attempts, respectively. Well that’s it for now. If you have any questions please post them below and I’ll try to answer. Otherwise stay tuned for more BIG-IP APM articles.
Thanks.
Good morning everyone,
Kevin, hi. I've tried what you suggested and even if it makes sense it does not work as expected (more than probably because even after all I've learn about NTLM thanks to this post i do not completely understand how it works). The irule used is below.
So, i will explain what i did/tried and what i suspect is failing. I have one policy that checks the Registry looking for the specific domain and if so the next step will be an Irule Event in VPE, "ntlm_on" (Now it does exists 🙂 ) After that I created an irule that starts with http_request -> "ECA disable" and if one specific APM session variable, "session.ntlm.required", exists and the content equal "yes", then ECA enable, else keep it disabled.
Besides that the same irule has ACCESS_POLICY_AGENT_EVENT that checks for ntlm_on. If it detects on it will set session.ntlm.required = yes and technically will start ECA thanks to HTTP_Request section above...It does not. Reviewing the logs i can see that the ntlm_on event is detected and the irule set the session.ntlm.required to yes. I believe that since is the same HTTP transaction and since NTLM technically happens at LTM level, not APM, it cannot be triggered again for the same request, therefore it may not be able to be activated in the middle of the policy verification. I am wrong? By the way, NTLM is working fine on my lab. Tested with the same computer and http_request ECA::Enable irule.
when HTTP_REQUEST {
ECA::disable
set ntlm_required no
if the user is a corporate user the policy will require NTLM auth. session.ntlm.required is set below
set ntlm_user [ACCESS::session data get "session.ntlm.required"]
if { $ntlm_user == "yes" } {
log local0. "NTLM_Enabled"
ECA::enable
ECA::select select_ntlm:/Common/NTLM_Auth
}
elseif { $ntlm_user == "no" } {
log local0. "NTLM_Disabled"
ECA::disable
}
}
when ACCESS_POLICY_AGENT_EVENT
{
if NTLM is required by the policy a new session variable will be created and used in the HTTP_Request event
if { [ACCESS::policy agent_id] eq "ntlm_on" }
{
log local0. "ntlm_required yes set"
ACCESS::session data set session.ntlm.required "yes"
}
elseif { [ACCESS::policy agent_id] eq "ntlm_off" }
{
log local0. "ntlm_required off set"
ACCESS::session data set session.ntlm.required "no"
}
}
After some additional testing, I believe that a Windows Registry check would require something closer to what Michael Koyfman has described. So for clarity, it basically boils down to something like this:
Simplified iRule:
when RULE_INIT {
set static::ntlm_config "/Common/F5NTLM"
}
when ACCESS_SESSION_STARTED {
ACCESS::session data set "session.ntlm.last.retries" 0
}
when HTTP_REQUEST {
switch -glob -- [string tolower [HTTP::uri]] {
"/ntlm/auth" {
if { [HTTP::cookie value MRHSession] ne "" } {
set sid [HTTP::cookie value MRHSession]
}
catch {
set sid [ACCESS::session sid]
}
set referer [HTTP::header value Referer]
set x_session_id [HTTP::header value X-Session-Id]
if { [string length $x_session_id] != 0 } {
set sid $x_session_id
}
set retries [ACCESS::session data get -sid $sid "session.ntlm.last.retries"]
set auth_result [ACCESS::session data get -sid $sid "session.ntlm.last.result"]
if { ($auth_result == 1) || (($retries == 2) && ($auth_result != 1)) } {
ECA::disable
HTTP::redirect $referer
} else {
ECA::enable
ECA::select select_ntlm:$static::ntlm_config
}
unset x_session_id
unset referer
}
default {
ECA::disable
}
}
}
when ECA_REQUEST_ALLOWED {
ACCESS::session data set session.ntlm.last.username "[ECA::username]"
ACCESS::session data set session.ntlm.last.domainname "[ECA::domainname]"
ACCESS::session data set session.ntlm.last.machinename "[ECA::client_machine_name]"
ACCESS::session data set session.ntlm.last.status "[ECA::status]"
ACCESS::session data set session.ntlm.last.result 1
ACCESS::disable
HTTP::header insert X-Session-Id $sid
use virtual [ virtual name ]
}
The set of ACCESS::session set commands in the ECA_REQUEST_ALLOWED event are not expressly required, but useful if you need to access NTLM user information from elsewhere. So basically, once the Windows Registry check determines this is a domain client, control is passed to an external logon page that redirects to itself at the /ntlm/auth URI. The HTTP_REQUEST event in the iRule is triggered and enables/disables ECA based on where you are in the policy evaluation. Once NTLM/ECA succeeds, the ECA_ALLOWED_REQUEST event disables access evaluation and injects the X-Session-ID header.
It's worth noting that if you simply performed an IP subnet check in an iRule, you wouldn't need to do all of this.
