Skip to content

mod_auth_vas Installation

Jump to bottom
Tyler Reese edited this page May 21, 2019 · 8 revisions

Overview

This guide describes how to install 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, One Identity does provide a few pre-compiled mod_auth_vas packages for some of the more popular and stable operating system distributions.

Installing from RPM

SuSE with Apache 2.2.x

This section applies to SuSE, OpenSuSE, 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:

    • edit /etc/httpd/conf.d/auth_vas.conf and specify the protected directories (details),
    • or create .htaccess files in the directories to protect (details.)

  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 2.x

This section applies to more recent Red Hat systems 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:

    • edit /etc/httpd/conf.d/auth_vas.conf and specify the protected directories (details),
    • or create .htaccess files in the directories to protect (details.)

  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.

  1. 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

  2. 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.

  3. 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.

  4. 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 Authentication Services users, please submit a pull request!

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 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 chmodor chownso 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
Clone this wiki locally