DansGuardian Documentation Wiki

You are here: Main Index » user_identification_methods


Wiki Information

If you wake up at a different time,
in a different place,
could you wake up as a different person?
Chuck Palahniuk

Classifying Users

At DansGuardian's core is the idea of treating different people differently. Its umbrella name for this facility is ”multiple filter groups”.

In order to treat different people differently, DansGuardian first has to learn who's who. DansGuardian calls the process of identifying who's who “authentication”. It offers a choice of several different authentication/identification mechanisms.

You choose which authentication/identification mechanism to use, then configure DansGuardian accordingly. But which one should you choose? This document aims to help you decide.

Some Notes on Terminology

To be fully accurate, the terms “authentication” and “authorization” mean different things. “Authentication” is the process of identifying someone, while “Authorization” is the process of checking if someone is allowed to perform a particular action. Often the two things are performed together, often in quick sequence: first “authentication” figures out who the user is, then “authorization” checks if that person is allowed to do something. But it's also possible to have one without the other: for example websites typically proceed directly to “authorization”, asking in effect not “who are you?” but rather “are you allowed into this website?”. Categorizing users by IP address is another example of “authorization” without “authentication”, saying in effect “requests from this IP address are treated this way regardless of which individual is using the computer”.

The difference is a bit precious; it's awfully easy to use the wrong term. That's probably why in most places DansGuardian just says “auth” without getting too specific about whether that's “authorization” or “authentication”. Be warned that even though it isn't strictly correct to do so, the remainder of this document may fall prey to using the two terms more or less interchangeably.

The various methods of allowing access to a website –or a proxy– (Basic, Digest, NTLM, etc.) have nothing to do with enabling secure transactions with a website (SSL, TLS, https:, 443, that “golden key”, etc.). You can have secure transactions with a website even though you accessed it anonymously. And although you entered a “restricted” website you don't necessarily conduct any secure transactions there. There's not even any connection whatsoever between the two security mechanisms under the covers.

Some of the DansGuardian auth methods correspond to web access methods, but others do not. For example the DansGuardian “IP” and “Ident” auth methods involve exchanges done outside of the web access protocol itself and do not correspond to any of the web methods of granting access.

The DansGuardian auth methods discussed in this document all have to do with allowing access to the DansGuardian/Squid system. They have nothing to do with secure transactions; their presence or absence does not affect the ability to conduct secure web transactions through DansGuardian/Squid.

The acronym NTLM is a combination of two other acronyms: NT for New Technology (remember Windows NT?) and LM for Lan Manager (once upon a time the name for Microsoft's network file sharing). The term is sometimes used to mean any of several slightly different things:

  • Browsers automatically supplying web username/password without interrupting the user with a popup.
  • A more secure exchange of web username/password in a “challenge/response” format and without the password ever being exposed even to a malevolent network eavesdropper.
  • An exchange of web username/password that follows the defined NTLM protocol and explicitly includes the term “NTLM” in the relevant HTTP headers.

The first option is perhaps the most confusing. Exchange of web username/password using the NTLM protocol does not necessarily avoid interrupting the user with a popup (although this is often the case). And there are ways –such as username/password extensions– that semi-automatically or automatically send the relevant username/password when asked without using NTLM. All too often when someone says “NTLM” what they really mean is automatic web login like this.

The second option likewise is misleading. There are other ways of exchanging web username/password in a “challenge/response” format without exposing the password on the network. In particular the web standard “Digest” authentication does exactly that. (Anyway, it's not clear this level of security is needed just for permission to access a website.)

The third option (the “correct” one) is the one we use here. If you trace/sniff the HTTP headers and see the word “NTLM”, you're dealing with NTLM credentials exchange. You cannot tell just by looking at the browser display screen whether or not the credentials exchange is using NTLM (don't be fooled). You may see a popup asking for username/password even when the browser is using NTLM. And just because you don't see a popup asking for username/password doesn't necessarily mean the browser is using NTLM.

Inner Workings

What's This Called?

The original authorization built into the HTTP protocol whereby the web browser would sometimes throw up a message box asking the user for a username and password is called BASIC. The current HTTP protocol also includes an improved version, which is called Digest. The improved version generally looks the same to the user, who is still prompted in the same way to enter a username and password.

NTLM is (was?) “the Microsoft way” and is often associated exclusively with Internet Explorer and Windows. It's possible though to use the Windows versions of both Firefox and Mozilla in an NTLM environment. To enable NTLM on these browsers, set this about:config option (if it isn't already set)

network.automatic-ntlm-auth.allow-proxies true

Recent Safari-descended browsers also understand NTLM web authentication (even though they may not be able to respond automatically and if so will ask the user to [re]type in the credentials).

In theory many OSs already have an accessible Ident server. However some Ident servers may have been turned off or deleted in an effort to reduce security risks, or the network (especially firewalls) may have been instructed to not pass port 113 traffic. It's also possible that some Ident servers were turned off or deleted accidentally as a side effect of some other change. And some OSs either don't include an easily accessible Ident server or don't have an Ident server at all. So it may be necessary for you to make sure there's an Ident server running on every computer, and it may be necessary for you to tweak network and firewall configurations to pass port 113. (Open Source Software Ident servers are readily available for all common OSs if necessary, so you need never reach a “dead end”.) Use of Ident authentication does not require that port 113 traffic can pass all the way through your external firewall to the remote website computer (although once in a while -especially without a NAT firewall- something else may require it), rather Ident authentication only requires that port 113 traffic be allowed between the DansGuardian machine (which is often also the external firewall) on one end and the client computer on the other end.

To reiterate: Ident auth requires that port 113 traffic be fully allowed in both directions between the DansGuardian machine and every client computer. Partial blocking of port 113 traffic by either network infrastructure devices (such as smart hubs) or software firewalls on individual computers (for example the one built in to Windows) is the usual cause of strange delays and timeouts and incorrect filter group assignments with Ident auth.

Some Basics of How It Works

Once DansGuardian identifies a user (and so can assign the request to the proper filter group), it remembers the identity (usually the username) and filter group, and automatically associates it to all subsequent requests over the same local proxy connection. So almost all requests are assigned to the proper filter group right from their beginning.

DansGuardian (and Squid) offer ways of “stacking” different authorization methods so if one fails the next one is used instead. However such configurations can be rather complicated and often don't work quite the same way as naively expected. So here we make the simplifying assumption that only a single authentication method is actively being used on any one computer (modulo terminology issues, such as is NTLM/Basic “one” or “two” auth methods?). (The majority of installations use only a single authentication/identification method on any one computer, so this restriction is not overly artificial).

More Details of How It Works

In some (but not all) cases DansGuardian subcontracts fetching the authentication information to the local proxy (probably Squid). DansGuardian ultimately cares only about the username, even when it subcontracts fetching the authentication to the local proxy which then goes much further. DansGuardian never knows or cares anything about the password (not even whether or not the password is correct). This does not lead to any problem because Squid won't return web content that DansGuardian can filter until after the password has proved correct. So DansGuardian can simply assume “if it's here, it must be okay”.

Even though DansGuardian (and usually some parts of Squid) doesn't care about the password or its correctness, once started the authentication process must proceed all the way to checking the password for correctness. The HTTP standard does not provide for a user to launch the authorization process but then partway through say “just kidding”. Likewise built into Squid is the assumption that if an authentication process is started, it will complete and the result will be available to Squid “acl” processing. So in Squid you will always see the password actually being checked in some way (perhaps involving LDAP or Samba) even though the information may be unused and never communicated to DansGuardian at all.

(Using a Squid helper authentication program that always says the password is OK without actually checking it has the net effect of accepting usernames without checking the corresponding passwords. [This is what the auth helper program called fakeauth included in some Squid packages does.] Accepting all usernames without checking the corresponding passwords sounds simpler, but may not be such a good idea after all. Without requiring a matching password, usernames garbled by a typographical error would be accepted anyway. So the audit trails provided by the logs might be legally dubious.)

DansGuardian caters for the situation of an unauthenticated user needing to proceed with one web access in order to become authenticated by allowing “authentication required” responses through as a special case when any auth plugins which require assistance from the local proxy (currently BASIC, Digest, NTLM) are enabled. This firmly prevents what might otherwise turn into a Catch-22 where users couldn't access anything until they authenticated out of the default group (f1), but couldn't authenticate because they couldn't access anything.

Filter Group vs. Website Authentication

There may be a concern whether the local authentication sequence that provides information for filter group assignment ever gets confused with the remote authentication sequence for websites. It turns out there will never be any overlap or interaction or conflict between authorization to the local DansGuardian/Squid and to the remote website with the “explicit-proxy” configuration family.

In any “explicit-proxy” configuration, the local proxy and the remote website use somewhat different HTTP headers for authorization. So remote websites can use any authorization method they wish, even if it's different than the one used by DansGuardian/Squid. New users will always have their local password fetched, even if none of the remote websites they visit ever uses any kind of authentication. And no matter what remote websites may do, users will never be asked for their local password more than once. (Besides, the vast majority of remote websites don't require any kind of authorization at all.)

Confusion may however occur in a “transparent-intercepting” configuration (which you shouldn't have anyway in most cases). These configurations sometimes at first appear to work, but nevertheless operate incorrectly every so often (especially when accessing a website that requires authentication). Also, such configurations force the browser to re-authenticate to DansGuardian/Squid for every request, rather than authenticating just once per browser session. The increased activity and communications traffic will sometimes cause noticeable performance degradation. (These gotchas are the main reason use of any proxy-assisted authentication method in a “transparent-intercepting” configuration is simply marked unavailable in the table below. Only if administrators thoroughly understand the interactions and possible problems might they choose to try one of these configurations anyway).

Mechanism Comparison Table

  BASIC Digest NTLM Ident IP
What Is Identified person person person person machine
Source of Identification Information user user OS OS network
Works with Windows Terminal Service Y Y probably not currently not easily -
User (or "auxiliary" program) Must (Re)Type Password Y Y - - -
Requires Unchanging ("static") End User Computer IP Addresses - - - - Y
Available In "Explicit-Proxy" Environment Y Y Y Y Y
Available In "Transparent-Intercepting" Environment - 1 - 1 - 2 Y Y
Requires Local Proxy Assistance (Local Proxy Requests/Validates, then DansGuardian "sniffs") Y Y Y - -
DG Release That Directly Supports 2.8+ 2.9+ 2.8+ 2.8+
Ease of User Spoofing medium very hard hard very easy easy
Mixed Broswers Y Y probably Y Y
Mixed Client OSs Y Y maybe almost always Y

1 May sometimes appear to work. But will get confused when accessing websites that require authentication, as filter group and website authentication reuse the same HTTP headers. And may extract a performance penalty, as filter group authentication must be re-done for every request rather than just once per browser session.

2 May appear to work. But may fail to access websites that negotiate NTLM authentication (no publicly accessible website should, but accidents are especially likely with IIS relying on its default configuration). And may extract a performance penalty, as filter group authentication must be re-done for every request rather than just once per browser session.

Software Configuration Support

Directly Supported Methods

Both the 2.8 and 2.10 series of DansGuardian directly support these user authorization/identification mechanisms:

  • BASIC (Web Browser)
  • IP (Network)
  • Ident (OS)

The 2.10 series of DansGuardian also directly supports:

  • NTLM (Especially IE Web Browser & Windows OS)
  • Digest (Web Browser)

(“Directly” means with the same DansGuardian/Squid configuration as for without any authentication at all, i.e. with only one copy of Squid.)

(The “Digest” user authorization/identification mechanism was first directly supported in version

Indirect Methods

A “sandwich” configuration
     Client ⇔ Squid1 ⇔ DansGuardian ⇔ Squid2 ⇔ Internet
can generally be made to work to support other authorization/identification mechanisms. (DansGuardian in the middle is the meat; the two Squids on either side are the bread; “sandwich” - get it?) Most often this kludge is used with DansGuardian 2.8 to support the authorization methods it doesn't support directly:

  • Digest (this kludge is not needed with recent 2.9/2.10 versions)
  • NTLM (this kludge is not needed with the 2.9/2.10 series)

Squid1 can be configured to perform authentication/identification according to the desired method, then pass the username information along to DansGuardian in the form of BASIC credentials with dummy passwords.

(Note the actual authorization/identification method as configured in the local proxy [probably Squid] may be different from the authorization/identification information forwarded to and processed by DansGuardian. For example DansGuardian and the browser may refer to what they're doing as Basic authentication even though Squid checks the credentials against LDAP.)

This “sandwich” configuration is generally a little more complex than usual, and should not be used unless it's really necessary. For example small errors (such as forgetting to disable caching in Squid1) can result in both severe performance degradation and partial failure of content filtering in some circumstances. For another example, if the environment involves two separate instantiations of Squid and there are inconsistencies between their configurations, unintended consequences may include such things as some websites being either never accessible or always accessible.

(It might sometimes be possible to configure just one physical copy of Squid so it functions logically as both Squid1 and Squid2. However the complication of the configuration is likely more trouble than it's worth, and such a configuration is not covered here.)

Extending Direct Support

In theory it's possible to add direct support for other authorization/identification methods by coding custom “authorization” plugins for DansGuardian. However decently complete documentation of how to do this has not presented itself, and the coding is trickier than might be expected; as a result this approach is not for the faint of heart. (Besides, there are very few web auth mechanisms in common use that aren't already supported by DansGuardian.)

It's seemingly not possible to make DansGuardian directly support Kerberos authorization/identification. Trying to extend DansGuardian with an auth plugin to provide direct Kerberos support would run afoul of the same problem that explains why no such plugin is provided with DansGuardian. The problem is that in the exchange, the Kerberos credentials are so heavily encrypted that DansGuardian cannot extract even a username. The usual indirect solution instead is to use BASIC authentication between browsers and DansGuardian/Squid, and then have Squid use LDAP to verify those already known plain text credentials with the Kerberos service.

Although direct NTLM support has been available in the 2.9/2.10 series of DansGuardian since early 2006 (and direct Digest support for quite a while), much available documentation still does not reflect it. It's unfortunately still very common to find HowTo's that mis-state that the way to get NTLM support (or Digest support) in DansGuardian is with the “sandwich” configuration.