Brief Description of This Module

mod_auth_ntdom is an access cheking module for Apache. It defers authentication requests to NT domain controller on network with help by underlying Samba modules statically linked-in. It also offers access control based on group list retrieved from the domain controller.

Overall Design

This module, mod_auth_ntdom, was designed and implemented in our pursuit for Single Sign-On(SSO) in "web-centered" application system, which is to say a system that requires its users only one login to the front-end web server to use multiple application servers (e.g., web servers and Metaframe servers). Although we are well-aware of secure and sophisticated authentication scheme that realizes SSO such as Kerberos, we determined that there exist needs for a much simpler one--HTTP basic authentication. That was the start point for this mod_auth_ntdom project.

In HTTP basic authentication, your login account and password are sent across network in clear text format. It might be a good idea to protect such important messages from being sniffed by means of message encryption such as Secure Socket Layer(SSL). Once received by the front-end web server, the password is "cached" for later use. The cache mod_auth_ntdom utilizes is actually environment variable stored in memory area associated with Apache subprocess so that CGI programs or servlets that the same user executes can retrieve the cached password throughout the session. It is not difficult to write a servlet that does login to other protected servers on behalf of the user when s/he clicks corresponding link on a web page. (Hmm... You might need to slightly modify Apache code depending on what you want to do. Details are left for readers. :)

Needless to say, an important prerequisite for SSO is Single-User-SinglePassword (SUSP). Without SUSP, there's no way to guarantee the above internal login by the front-end web server would be successful. This is another place where mod_auth_ntdom comes into play. With this module, Apache sends authentication requests to NT domain controller. Alternatively, you can use NIS server, Samba server or LDAPaccessible directory as the single point of authentication control on your network.

Another role mod_auth_ntdom plays is access control. Upon a successful authentication, it retrieves the list of groups that the authenticated user belongs to from the Security Accounts Manager(SAM) database residing on the NT domain controller. The retrieved group list is "cached" until access control by group is requested through "require group" directive in httpd.conf or access.conf file. The cached group list is stored, again, in memory associated with Apache subprocess; however, unlike cached password, this list itself is inaccessible from CGI programs and servlets. When web contents are restricted by "require group" directive AND if access is granted, the group name, under which access is granted, is set to environment variable; and, therefore, gets accessible from the programs. In short, only a valid group for accessing a web content is visible inside the content. Well, then, what if you belong to, say, two groups are both are legitimate group to access to the content? The answer is that it depends on the order of group names appeared in "require group" directive. The leftmost group name has the highest precedence.

Environment Variables Set by This Module

As described above, a few custom environment variables are set by mod_auth_ntdom, in addition to REMOTE_USER Apache usually sets, for the purpose of application-level single sign-on and access control:

REMOTE_DOMAIN NT domain name
REMOTE_USER_PASSWORD user password

REMOTE_GROUP            a legitimate group, which the user belongs to,
                        for accessing the content

If you don't need and/or don't want to set these environment variables, you can do so by setting NTAuthSetRemoteDomain/NTAuthSetRemoteUserPassword/ NTAuthSetGroup to off in httpd.conf/access.conf file.

When using with Apache JServ 1.1, you might need to set ApJServEnvVar directives as well in order to successfully pass these custom environment variables to your servlets.

Samba Source Dependency

mod_auth_ntdom heavily relies on a number of programs included in Samba-2.0.7. Most of them are just "borrowed" in source form, compiled, linked with mod_auth_ntdom. So, you need to have Samba-2.0.7 source distribution in order to make mod_auth_ntdom.

cmd_lsarpc.c and cmd_samr.c, which are included in this distribution, in contrast, have been stripped down from their original code found in Samba-2.0.7 and also slightly modified to serve the purpose of mod_auth_ntdom. RPC client code in ntdom_validate_user() is based on rpcclient.c.

httpd.conf/access.conf Directives

The following directives can be used in your access.conf file in the same way as you would configure the standard authentication modules:

NTAuthEnabled <flag>
Determines if NT domain authentication is enabled. Default is on.

NTDomainName <Domain Name>
Specifies the NT domain name here.

NTPDC <PDC Name>
NTBDC <BDC Name>
Specifies the NetBIOS name for Primary and Backup Domain Controller for the domain specified by NTDomainName directive.

NTGroupAlias <Group Alias> <Domain Group RID in hexadecimal digits> Specifies alias for domain group RID which domain controller returns. With the use of this directive, descriptive names such as "Operators" can be used in "require group" directives and are also passed by REMOTE_GROUP environmental variable. Well-known group RID (i.e., ADMINS:200, USERS:201, GUESTS:202) are set by default.

NTAuthDebug <flag>
Determines if debug mode is enabled. Default is off.

NTAuthDebugLevel <integer>
Specifies the level of debug message that underlying Samba modules write in the Apache error log. 0 is minimal debug level. If you want no Samba debug messages at all, specify a negative number.

NTResolveOrder <resolve order string>
Specifies the order of name resolver. "host", "bcast", "wins", "lmhost", and their combinations are allowed. (e.g., NTResolveOrder "lmhosts host wins bcast")

NTWinsIP <IP address>
Specifies IP address of your WINS server IP address. Ignored if "wins" not specified in NTResolveOrder.

NTAuthSetRemoteDomain <flag>
Determines if mod_auth_ntdom sets REMOTE_DOMAIN environment variable. Default is on.

NTAuthSetRemoteGroup <flag>
Determines if mod_auth_ntdom sets REMOTE_GROUP environment variable. Default is on.

NTAuthSetRemoteUserPassword <flag>
Determines if mod_auth_ntdom sets REMOTE_USER_PASSWORD environment var. Default is off.
BE CAREFUL in setting this to on!!!
Your password in clear text form would be visible in CGI programs and servlets you execute yet you might find this feature useful when establishing Single Sign-On environment.

The require directives are as follows:

require valid-user
Allows any valid NT domain user.

require user <username>
Allows the specified user.

require group <group RID or group alias> Allows access to anyone in the given group.