Apache authentication

mod_auth_vas - Installation

Overview

This guide describes how to install Resource Central's mod_auth_vas Apache authentication module. Step-by-step instructions are given for an example web server setup on various platforms.

The mod_auth_vas module is intended to be compiled from source form for your particular version of Apache HTTPD. This is because the Apache web server's module API changes substantially between different releases and modules compiled for one version of the Apache web server are not guaranteed to function correctly with another. However, Resource Central does provide a few pre-compiled mod_auth_vas packages for some of the more popular and stable operating system distributions.

Listed below are the latest releases of mod_auth_vas, including both binary and source packages:

  NOTE: Packages for Linux distros using Apache have "ap" in their names. Packages for Red Hat's httpd have "http" in their names.

Release: mod_auth_vas-3.6.8.4
Platform Filename Type Size Date MD5 checksum?
Other mod_auth_vas releases
aix-53mod-auth-vas53-IHS20.3.6.8.4.bffpackage563 kB2015-01-20b2ec8c05a65d29546196e21866d35835
hpux-pa-11v1mod-auth-vas-ap20-3.6.8.4.hppa.depotpackage492 kB2015-01-208c08095e55b6a266cbc23b3b43a89a26
linux-ia64mod-auth-vas-ap20-3.6.8.4-1.ia64.rpmpackage76 kB2015-01-2087531f6e5189893acae3b1f305025327
linux-ppcmod-auth-vas-ap20-3.6.8.4-1.ppc.rpmpackage69 kB2015-01-20647a92581f105fc1fdd806da416dafaf
linux-x86_64mod-auth-vas-ap20_3.6.8.4-1_amd64.debpackage79 kB2015-01-20821a3e10d3e8e36d794c202a93850c46
mod-auth-vas-ap22-3.6.8.4-1.x86_64.rpmpackage80 kB2015-01-20693cbd37f0fa9eb78cb40d30080e4e13
mod-auth-vas-ap22_3.6.8.4-1_amd64.debpackage79 kB2015-01-2083597f8ea3f3f473068fd52d85b307cd
mod-auth-vas-http20-3.6.8.4-1.x86_64.rpmpackage69 kB2015-01-20a88ed12457b7d9d7595b4f5ef70e2642
mod-auth-vas-http22-3.6.8.4-1.x86_64.rpmpackage80 kB2015-01-20d7cdf960d88bf9343abdd3d9a5dd2239
linux-x86mod-auth-vas-ap20_3.6.8.4-1_i386.debpackage70 kB2015-01-20be56e1bbe156331143aa71a58c44a0a6
mod-auth-vas-ap22-3.6.8.4-1.i386.rpmpackage75 kB2015-01-20db98bf1610ac81df3c72f6f0505f73c4
mod-auth-vas-ap22_3.6.8.4-1_i386.debpackage75 kB2015-01-2055ae4e981f0403c9863a75a9dc0b2e76
mod-auth-vas-http20-3.6.8.4-1.i386.rpmpackage67 kB2015-01-2031f113e29a260e5147cd4ec8ce96c1f4
mod-auth-vas-http22-3.6.8.4-1.i386.rpmpackage77 kB2015-01-20d9b69c0ce548400523a95f091ab9e02e
solaris10-sparc64mod-auth-vas_SunOS_5.10-ap22-3.6.8.4-sparc64.pkgpackage208 kB2015-01-20297f4da1d7ce80f21e0c85bafaa6a507
solaris10-x64mod-auth-vas_SunOS_5.10-ap20-3.6.8.4-i386.pkgpackage223 kB2015-01-20bd9695735e0cb669210aa356b574b221
solaris8-sparcmod-auth-vas_SunOS_5.8-ap22-3.6.8.4-sparc.pkgpackage178 kB2015-01-20f94e67b6a01790c67f70a246ae12aa36
solaris8-x86mod-auth-vas_SunOS_5.8-ap22-3.6.8.4-i386.pkgpackage163 kB2015-01-200d2306aeb980865408b8e42407ed6dcb
sourcemod_auth_vas-3.6.8.4.tar.gzsource611 kB2015-01-20806a6dafa7781f965acfb988fc9f72bd

Installing from RPM

SuSE with Apache 2.2.x

This section applies to SuSE 9.3, 10.0, OpenSuSE 10.0, and other modern derivations of SuSE with apache2 installed.

1. Use the following command to install the RPMs:

# yast2 -i mod_auth_vas-ap22-3.6.8.4.i386.rpm

2. Run the setup script to create a HTTP service and check file permissions:

# /opt/quest/sbin/setup-mod_auth_vas

3. Either:

4. Finally, activate mod_auth_vas by restarting the web server:

# /etc/init.d/apache2 restart

5. Check /var/log/apache2/error_log for error messages.

Red Hat with Apache 1.3.x

This section applies to older Red Hat systems, such as Red Hat Linux 7.3 with apache-1.3 installed.

Packages for apache 1.3 are no longer available for the latest releases of mod_auth_vas, and must be compiled from source. For directions on how to install mod_auth_vas from source See Install mod_auth_vas from source

Red Hat with Apache 2.x

This section applies to more recent Red Hat systems, such as Red Hat Enterprise Linux 3.0 or 4.0 with httpd-2.0 installed.

1. Use the following command to install the RPMs:

# rpm -Uvh mod_auth_vas-http20-3.6.8.4.i386.rpm

2. If you have not created a HTTP service account, do so now:

# /opt/quest/sbin/setup-mod_auth_vas

3. Either:

4. Finally, activate the module by starting or restarting the web server.

# /etc/init.d/httpd restart

5. Check /var/log/httpd/error_log for error messages.

Installing mod_auth_vas from source

This section applies to any system where an Apache web server, or derivative, is installed.

  1. Prerequisites:
    • Quest Authentication Services 3.0 or later
    • the Quest Authentication Services developer kit vasdev (found in the SDK directory on the Authentication Services CD)
    • a C compiler (e.g. gcc)
    • Your Apache HTTPD's extension tool (look for a program called apxs or apxs2)
    • make. GNU make is necessary to create a platform-native package (such as an RPM). Otherwise any sane version of make will be fine.
  2. Download the source package, mod_auth_vas-[version].tar.gz
  3. Unpack and build the source package:
    $ gzip -dc < mod_auth_vas-3.6.8.4.tar.gz | tar fx -
    $ cd mod_auth_vas-3.6.8.4
    $ ./configure
    $ make
    If this step fails, please double-check that you have all the required software listed in the earlier steps. You may need to provide the path to apxs explicitly with the --with-apxs option to configure.
  4. If your operating system uses dpkg (deb) or RPM packages, you can build a native package by running:
    $ make package
    The package will be built and put in the pkg directory, then you can install it with the appropriate command, eg. dpkg -i pkg/*.deb or rpm -i pkg/*.rpm . Otherwise install the module directly:
    # make install
  5. Enable the module:

    If you built & installed a package then the module will have been enabled automatically.

    If you installed the module manually you can enable it by adding LoadModule auth_vas_module /path/to/apache/modules/mod_auth_vas.so to your Apache config. You can find the module path by running apxs -q LIBEXECDIR . This LoadModule line should be added after the existing LoadModule lines to avoid a possible conflict between the system's libgcc_s.so and Quest Authentication Services' libgcc_s.so.

  6. Run the setup script. This will create the service account in Active Directory and set it up for use with mod_auth_vas, as well as checking that the local keytab file is usable by the Apache server:
    # /opt/quest/sbin/setup-mod_auth_vas
    You may need to use the -a and -c options to specify the location of apxs and Apache's config file. Run /opt/quest/sbin/setup-mod_auth_vas -h for details. It is safe to run setup-mod_auth_vas more than once, for example to review the state of the service account.
  7. Restart the Apache server. (Usually /etc/init.d/httpd restart or /etc/init.d/apache2 restart)

As the source is available, you are free to modify and enhance the module. If you extend mod_auth_vas in a way that is likely to be useful to other Quest Authentication Services users, please share the changes with us! Contact the web forum and we can add it to future distributions with credit.

Compiling for Oracle HTTP Server

When running the configure script, it is likely that the compiler reported by apxs will not work. In that case, re-run ./configure with CC=gcc at the end of the command-line to override the choice of compiler:

$ ./configure CC=gcc

If you get an error that strict.pm is not found when running apxs, consider changing the apxs script (Apache/Apache/bin/apxs) to use the system's perl instead of Oracle's bundled perl by changing the first line of the apxs script to

#!/usr/bin/perl
(or wherever your system's perl program is).

If you get an error loading libdms2.so when starting httpd, set the LD_LIBRARY_PATH environment variable to your ORACLE_HOME/lib directory.

Installing on a server that is not joined to the domain

Running on a server that is not joined to the same domain is not a supported configuration for mod_auth_vas. mod_auth_vas is designed to work on a machine that is joined to the same domain, however many configurations (such as a simple "Require valid-user") usually do work on a machine that is joined to another, untrusted domain or not joined at all. If it does work you might find that some operations are slow or cause more network traffic than when run on a server that is joined to the same domain.

To install mod_auth_vas on a machine that is not joined to the domain, the domain must be set in /etc/opt/quest/vas/vas.conf by adding a line in the "[libdefaults]" section like so:

[libdefaults]
  default_realm = EXAMPLE.COM

This should be done before executing the setup-mod_auth_vas script. All other installation steps are the same, including the requirement of having the Quest Authentication Services package(s) installed.

Configuring mod_auth_vas

After installing mod_auth_vas, you now need to configure the web server to enable it for authentication and authorization on the resources you want protected. The next sections detail this process.

Per-server configuration

mod_auth_vas understands the following directives when they are used in the httpd.conf file's global and/or <VirtualHost> sections.

AuthVasApiDebugLevel level

Debug verbosity levels for the Authentication Services API logging. Debug will be written out to system log under the name mod_auth_vas. Debug levels 0-6. Debug level 3 or higher will include nested logging when an error occurs from the LDAP or KRB5 layers of the API. The default is level 0. (Since mod_auth_vas 3.6.8.2)

AuthVasCacheSize size

The number of user objects to keep in mod_auth_vas's user cache. The default is 200. (Since mod_auth_vas 3.6.0)

AuthVasCacheExpire time

The amount of time (in seconds) after which cached user objects shall be expired from mod_auth_vas's user cache. The default is 60 seconds. (Since mod_auth_vas 3.6.0)

AuthVasNegGroupCacheSize size

The number of user objects to keep in mod_auth_vas's negative group cache. The default is 200. (Since mod_auth_vas 3.6.8.4)

AuthVasNegGroupCacheExpire time

The amount of time (in seconds) after which cached invalid group objects shall be expired from mod_auth_vas's negative group cache. The default is 60 seconds. (Since mod_auth_vas 3.6.8.4)

AuthVasDefaultRealm realm

Changes the default Active Directory domain to assume when matching usernames with Require user. The domain defaults to the realm to which the host is joined. The domain is also displayed to users when Basic authentication is being used. Defaults to the domain that Quest Authentication Services is currently using to join the web server host to Active Directory.
Note: An Active Directory 'domain' is the same as a Kerberos 'realm', and is usually written in uppercase, e.g EXAMPLE.COM. Active Directory domains should not be confused with DNS domains, although they're usually closely related.

AuthVasKeytabFile path

The keytab file containing the server's Kerberos credentials. If not set, it is automatically derived from the AuthVasServerPrincipal — usually /etc/opt/quest/vas/HTTP.keytab. (Since mod_auth_vas 3.6.0)

AuthVasServerPrincipal principal

Changes the user principal name (LDAP userPrincipalName) used by the web server. Defaults to HTTP/ which Quest Authentication Services expands to HTTP/hostname@realm, where hostname is the local machine's fully-qualified domain name, and realm is the realm (or domain) to which the host is joined. Normally this directive is not needed.

This option first appeared in version 3.6.0. It was previously called AuthVasServicePrincipal, but its meaning changed and the name became misleading. The old name is still supported.

A HTTP/ service key is necessary for your web server to engage in an SPNEGO exchange. The secret key is kept in two places: in a file accessible to the web server and in a host-based service account object inside the Active Directory server. The easiest way to create the service account and key is to use the setup-mod_auth_vas command on the web server:

# /opt/quest/sbin/setup-mod_auth_vas

Alternatively you can invoke vastool manually:

# vastool service create HTTP/

The above command creates the file /etc/opt/quest/vas/HTTP.keytab, which you should immediately chmod or chown so that the Apache web server can read it. The recommended permissions on the file are such that only the web server group can read it:

-rw-r----- 1 root apache 5600 Oct  4 09:28 /etc/opt/quest/vas/HTTP.keytab

Per-directory configuration

The following directives can be placed in a .htaccess file, or in a <Directory> or <Location> section within httpd.conf.

AuthType VAS
Enables the mod_auth_vas module during requests on the resource. It permits the module to deny access to the resource depending on the satisfaction of the Require directives.
AuthName string

Optional string to be used in Basic authentication prompts. If not set, the Kerberos realm will be used instead. See also Apache's documentation on AuthName.

AuthVasAuthoritative [On|Off]

If this option is turned Off, mod_auth_vas will perform authorization checks but instead of immediately denying an unauthorized user, other configured authorization modules will be tried.

This option only affects what happens when a user is not authorized. If a user is authorized by mod_auth_vas then they will always be allowed access. The default is On.

default (both on) AuthVasAuthoritative Off AuthVasAuthz Off
Do mod_auth_vas authorization checks? yes yes no
Try other modules if authorization fails? no yes yes

See also AuthVasAuthz and Apache's documentation on Authentication, Authorization and Access Control.

AuthVasAuthz [On|Off]

Can be set Off to disable mod_auth_vas authorization checks. This might be useful if you want to use both Negotiate (SSO) and Basic (password) authentication, but you want to use another module to do all the authorization checks. For instance this can be used with mod_authz_svn which also has a "Require valid-user" option that bases its authorization decisions on the contents of its AuthzSVNAccessFile. The default is On, meaning mod_auth_vas will provide authorization checks.

See also AuthVasAuthoritative and Apache's documentation on Authentication, Authorization and Access Control. Since 3.6.0.

AuthVasExportDelegated [On|Off]
Stores delegated credentials in a temporary credential cache file on each request. The default setting is Off. The path to the file is supplied in the KRB5CCNAME environment variable. Note that the created file is owned by the web server user and may be inaccessible when SUEXEC is active. It is deleted when the request completes.
AuthVasLocalizeRemoteUser [On|Off]
This option is deprecated. It is equivalent to AuthVasRemoteUserMap local.
Translates usernames in the REMOTE_USER variable to their local names. The default setting is Off. For example the user john@EXAMPLE.COM would be translated to username john if the server is in the EXAMPLE.COM realm. (Since mod_auth_vas 3.4.0)
AuthVasNTLMErrorDocument [ default | message | document ]
mod_auth_vas provides a built-in error page to clients that try NTLM authentication. The error page contains some hints on browser configuration. It can be overridden in a per-directory context in a similar way to Apache's ErrorDocument option, namely by specifying a custom error message or URL. For example:
AuthVasNTLMErrorDocument default
AuthVasNTLMErrorDocument "NTLM not supported" 
AuthVasNTLMErrorDocument /errors/ntlm.html
We recommend configuring your own site-specific document that covers the most likely solutions for your users. Don't forget to make the error page accessible by unauthenticated users. Use a <Files> container with Satisfy any to make exceptions, or store it in an unprotected directory. (Since mod_auth_vas 3.5.0)
AuthVasRemoteUserMap [ default | local | ldap-attr attr ]
Determines how the REMOTE_USER variable should be set. The parameter has the following meaning
  • default: the user's Kerberos principal name (sAMAccountName@REALM, eg. john@EXAMPLE.COM)
  • local: A local representation of the user. This means the canonical local username if they belong to the same realm, or the user's full Kerberos principal name for cross-realm users. All authenticated users regardless of Unix-enablement will be localized in this manner.
  • ldap-attr attr: Any LDAP attribute fetched from the authenticated user's Active Directory user object. The following attributes are usually resolved from the Quest Authentication Services cache and do not cause LDAP traffic:
    • userPrincipalName
    • sAMAccountName
    • distinguishedName
    • objectSid
    • uidNumber
    • gidNumber
    Other LDAP attributes will cause LDAP traffic for each request.
(Since mod_auth_vas 3.5.0)
AuthVasSuexecAsRemoteUser [On|Off]
Configures mod_suexec to execute CGI scripts as the remote authenticated user. This option overrides mod_suexec's SuexecUserGroup directive (which can only be specified per-server and not per-directory). If mod_suexec is not loaded, this option has no effect.
The default setting is Off.
This option was added in mod_auth_vas 3.5.0. Prior to that, mod_auth_vas behaved as if this option was On.
AuthVasUseBasic [On|Off]
Enables/disables use of the Basic authentication fallback when the web browser/client does not understand the reply header WWW-Authenticate: Negotiate. When enabled, a second reply header is sent to the client: WWW-Authenticate: basic. This is sufficient for some browsers to prompt the user for their login name and password, and retry using Basic authentication. If the web server is not using SSL (HTTPS), then the user's password will be visible on the network. This configuration inherits its settings from parent directories. The initial setting is Off.
AuthVasUseNegotiate [ On | Off | subnet... ]
Enables/disables use of Negotiate authentication (SPNEGO). This configuration inherits its settings from parent directories. The initial setting is On.
Negotiate authentication can be enabled on a subnet-specific basis by specifying a list of subnets instead of On or Off. Subnets are specified in the network/mask notation. The optional /mask can be an IP address or the number-of-bits (CIDR notation). If left out, the mask is assumed to be /32 for IPv4 or /128 for IPv6, that is, exact IP address matching is performed. Multiple subnets may be specified, separated by spaces. Examples of directive use:
AuthVasUseNegotiate On
AuthVasUseNegotiate Off
AuthVasUseNegotiate 10.0.0.0/8 127.0.0.0/255.0.0.0
Examples of valid subnet expressions (IPv6 only available on Apache 2):
127.0.0.1
127.0.0.0/8
127.0.0.0/255.0.0.0
::/128
fe80::/ffff::
The AuthVasUseNegotiate option can be used on machines that serve both internal (Kerberos-capable) and external clients. It can prevent the external Internet Explorer clients erroneously trying to use NTLM authentication. See bug 337.
Support for subnet-specific Negotiation was added in mod_auth_vas 3.5.0. Prior to that it could only be On or Off.
Require user upn...
Causes the authorization phase to succeed if the authenticated user principal name matches any of the given user principal names. An example of a user principal name is john@EXAMPLE.COM. Each upn may also be a simple username, in which case the default realm (see AuthVasDefaultRealm) will be automatically appended.
Require group group...
Causes the authorization phase to succeed if the authenticated user is a member of any of the Active Directory groups named. Group names containing spaces should be quoted with double quotes.
Require unix-group group...
Causes the authorization phase to succeed if the authenticated user is a member of any of the unix groups. (Since mod_auth_vas 3.3.0)
Require container dn...
Causes the authorization phase to succeed if the authenticated user is within any of the given Active Directory containers named by the distinguished name dn. Normally, these are organizational unit names expressed as X.500 distinguished names. For example:
Require container "cn=Employees, dc=example, dc=com"
Require valid-user
Causes the authorization phase to succeed if the user was authenticated. Any user that can obtain a ticket for the web service will satisfy this requirement. This allows you to trust all forests and domains that share some kind of trust relationship with the Active Directory server with which your web server host has joined.

See also: AuthType, Require, AuthAuthoritative

Configuring for virtual hosts

It is common to have a single Apache HTTP server serving multiple different sites for different hostnames. It is called virtual hosting and mod_auth_vas is capable of providing access control for virtual hosts.

Setting up a virtual host

There are several steps involved in setting up a virtual host to use mod_auth_vas for single sign-on. The following example assumes a web server with the hostname server123.example.com and with a DNS CNAME alias www.example.com. Clients will either access the site as http://server123.example.com/ or as http://www.example.com/. The server only needs to know that it is called server123.example.com, so long as there are servicePrincipalName entries in LDAP matching the names clients will use to access the server.

1. Make sure the HTTP/ service has been created. The simplest way is to run

# /opt/quest/sbin/setup-mod_auth_vas
as root. The setup-mod_auth_vas script will handle creation of the HTTP/ service account in Active Directory and the local keytab. It won't add any SPN aliases.

You could also manually create the service account using the vastool service create command. See the vastool manual page for more information.

Once you have created the HTTP/ service account, check what SPNs are attached to it by using vastool attrs:

$ vastool attrs -s HTTP/server123.example.com servicePrincipalName
servicePrincipalName: HTTP/server123.example.com

A newly-created service will have just one SPN. Keep a record of the existing servicePrincipalName values for the next step.

2. Add more servicePrincipalName attribute values using the vastool setattrs command. You must specify the existing servicePrincipalName values on the command line, otherwise they will be replaced. For example:

$ vastool attrs -s HTTP/server123.example.com servicePrincipalName
servicePrincipalName: HTTP/server123.example.com
$ vastool setattrs -sm HTTP/server123.example.com servicePrincipalName \
  HTTP/server123.example.com HTTP/www.example.com
Attribute changed: servicePrincipalName

Check that the new SPNs have been correctly updated:

$ vastool attrs -s HTTP/server123.example.com servicePrincipalName
servicePrincipalName: HTTP/www.example.com
servicePrincipalName: HTTP/server123.example.com

Quest Authentication Services 3.1.2.45, 3.2.0.109 and earlier only: current versions of Quest Authentication Services use implicit aliasing when matching entries in the keytab, making this step unnecessary.

3. Set up the alias in the local keytab file. Unlike vastool setattrs, you do not need to specify existing alias when creating keytab aliases:

# vastool ktutil -k /etc/opt/quest/vas/HTTP.keytab \
  alias HTTP/server123.example.com HTTP/www.example.com

Confirm the alias has been added:

# vastool ktutil -k /etc/opt/quest/vas/HTTP.keytab list
/etc/opt/quest/vas/HTTP.keytab:

Vno  Type              Principal
  2  arcfour-hmac-md5  server123-HTTP@EXAMPLE.COM
  2  arcfour-hmac-md5  HTTP/server123.example.com@EXAMPLE.COM
  2  arcfour-hmac-md5  HTTP/www.example.com@EXAMPLE.COM

4. Adjust the Apache configuration files as necessary. This means adding AuthType VAS to enable mod_auth_vas for that <VirtualHost>, and setting access controls with Require directives. mod_auth_vas determines the ServerPrincipalName to use automatically based on the ServerName, which is usually correct. This can be overridden with mod_auth_vas's AuthVasServerPrincipal option. The AuthVasDefaultRealm option is also useful for cross-domain environments.

<VirtualHost *:80>
    ServerName www.example.com
    AuthVasServerPrincipal HTTP/server123.example.com@EXAMPLE.COM
    AuthVasDefaultRealm EXAMPLE.COM
</VirtualHost>

Virtual host troubleshooting tips

Example configuration files

Here is a simple .htaccess that authenticates everyone except anonymous users:

AuthType VAS
Require valid-user

Here is a more complicated example .htaccess:

AuthType VAS
Require user alice bob alice@ELSEWHERE.COM
Require group finance
Require group it
Require group "Domain Admins"
Require container "ou=Sales, dc=example, dc=com"

AuthVasUseBasic on
If the server is joined to the EXAMPLE.COM domain, then the directives above allow the following users to access files in the directory:

The last line (AuthVasUseBasic on) enables the insecure 'Basic' authentication fallback, and should only be used with HTTPS.

Here are example fragments for httpd.conf:

AuthVasDefaultRealm EXAMPLE2.COM
<Directory "/srv/www/mytestdir">
    AllowOverride All
    AuthType VAS 
</Directory>
<VirtualHost *:80>
    ServerName www.example.com
    AuthVasDefaultRealm EXAMPLE.COM
    AuthVasServerPrincipal HTTP/www.example.com@EXAMPLE.COM
</VirtualHost>

The first line changes the default realm, used by the Require user directive. The <VirtualHost> section gives an example of how different service keys can be used.

Known limitations

The following are known limitations with mod_auth_vas:

See also: the troubleshooting guide, or the product bug tracker.

- David Leonard