Stanford WebAuth Installation Instructions

OVERVIEW

This document describes installation of WebAuth for web server administrators at Stanford University, including Stanford-specific configuration and setup details. For general installation instructions, see the INSTALL file at the root of the WebAuth distribution.

If you have trouble with these instructions, please file a HelpSU ticket giving your system name, the operating system it's running, how far you got in these instructions, and exactly what is failing (including error messages and similar information).

COMPILING, TESTING, and INSTALLATION

Where possible, you should use pre-built WebAuth packages rather than building WebAuth yourself. The pre-built packages are built with known options and tested for compatibility and functionality with the operating system platforms on which they're built. They also mean less installation effort.

For Debian or Ubuntu users, install the libapache2-webauth package. This package is included in the base releases of both Debian and Ubuntu. Newer versions for Debian may also be available from the backports.debian.org repository; see:

<http://backports.debian.org/Instructions/>

for information on how to install packages from backports.debian.org.

To use mod_webauthldap, also install libsasl2-modules-gssapi-mit or libsasl2-modules-gssapi-heimdal to enable GSS-API authentication via SASL for the LDAP libraries.

For Red Hat Enterprise users, WebAuth packages are available from our local yum repository. See:

<http://www.stanford.edu/services/linux/up2date-yum-repos.html>

for information on how to configure your system to install packages from Stanford's local repository. You can also simply download and install the RPMs from the WebAuth distribution page at:

<http://webauth.stanford.edu/download.html>

but it's better to use the yum repository if possible since then you can easily install newer versions as they're released. The package name for Red Hat systems is just webauth.

For Fedora users and other Red Hat users who cannot use the RHEL packages unmodified, the best approach is probably to start from the source packages available on the WebAuth distribution page and rebuild them for your local system.

On other platforms, you will need to build and install WebAuth yourself. Follow the general installation instructions up through the INSTALLATION section, and then return to this document.

CONFIGURATION

Apache Directives

On Debian or Ubuntu, create /etc/apache2/conf.d/stanford-webauth.conf with the following contents:

    WebAuthLoginURL  https://weblogin.stanford.edu/login/
    WebAuthWebKdcURL https://weblogin.stanford.edu/webkdc-service/
    WebAuthWebKdcPrincipal service/webkdc@stanford.edu

and then run a2enmod webauth. Depending on the Apache version, you may also need to run a2enmod authz_user. That's all the custom Apache configuration you should need on those platforms. It's best to put this configuration in a separate file rather than adding it to the files in /etc/apache2/mods-available, since it keeps it separate from the configuration that is maintained by the module package during upgrades.

On Red Hat Enterprise Linux 4 or 5 (or equivalent) systems, create the file /etc/httpd/conf.d/stanford-webauth.conf with the same contents as given above.

For other systems, such as systems where one has built Apache and WebAuth by hand, copy conf/stanford-webauth.conf from the WebAuth source tree into your Apache 2.x conf directory and then add the line:

    Include conf/stanford-webauth.conf

in the Apache httpd.conf file. This file assumes that the WebAuth module is installed in /usr/local/libexec/apache2/modules. You will need to change the LoadModule line in that file if it's installed in some other path. You will also need to ensure that the directory conf/webauth under your Apache root directory exists and is writable by the running web server. That directory should be writable by the user and group specified in the User and Group directives in your httpd.conf. This is taken care of for you on Debian, Ubutu, and Red Hat.

Keytab

To use the Stanford WebAuth service, you will need to create a keytab for the principal webauth/<system> where <system> is the fully-qualified hostname of the host. You do this using the wallet program.

First, install the wallet client on your system. Instructions for how to do this are at:

<http://itservices.stanford.edu/service/kerberos/wallet>

Next, ensure that you are listed in NetDB as the administrator, user, or admin team member for the system on which you're installing WebAuth. Permissions to download keytabs for systems is controlled by the NetDB data for that system. (If you are installing WebAuth on a system that's not registered in NetDB, such as an external system used for Stanford purposes, but still want to use the Stanford WebAuth service, file a HelpSU ticket with the name of the system so that a wallet entry can be custom-created for it.)

Determine the path into which the keytab should be installed on your system. If you are using the Debian, Ubuntu, or Red Hat packages, this path should be /etc/webauth/keytab. If you are using your own build of WebAuth, it should be conf/webauth/keytab under your Apache root. The location is controlled by the WebAuthKeytab directive in the Apache configuration.

Finally, create the keytab with wallet:

    wallet -f <path> get keytab webauth/<system>

where <path> is the path as determined above and <system> is the fully-qualified name of the system.

After installing the keytab, make sure it is readable by the user and group that the web server runs as. Usually this can be done with:

    chmod 640 <path>
    chgrp apache <path>

or whatever group is specified in the Group directive of your Apache configuration.

SSL Certificate

An SSL certificate is required to use WebAuth. Stanford users who need an SSL certificate for university applications can obtain one for free from the university's SSL certificate vendor. For more information, see:

<https://itservices.stanford.edu/service/ssl>

If you do not want to use an SSL certificate through this service or are not eligible, see the SSL Certificate section in the regular installation instructions for details on how to create a self-signed certificate. Or, of course, you can purchase your own certificate separately or use an organization like cacert.org.

If you are using the Debian or Ubuntu Apache packages, you will need to explicitly enable the SSL Apache module with a2enmod ssl. You will then also need to configure the location of your SSL certificate and key file. For Debian and Ubuntu, the best location for the certificate is /etc/ssl/certs, and for the key is /etc/ssl/private. Example configuration:

    SSLCertificateFile    /etc/ssl/certs/<hostname>.pem
    SSLCertificateKeyFile /etc/ssl/private/<hostname>.key
    SSLCipherSuite HIGH:MEDIUM:!ADH:!SSLv2:@STRENGTH
    SSLProtocol all -SSLv2

The last two configuration lines disable weak SSL ciphers. You can use similar configuration directives for other operating systems, but may need to change SSLCertificateFile and SSLCertificateKeyFile. Depending on what instructions you use to generate the certificate, the file extension may be .crt instead of .pem. Conventions vary on how to name the public key file.

See /usr/share/doc/apache2.2-common/README.Debian.gz for more information about configuring SSL on Debian and Ubuntu systems, including how to generate and use self-signed certificates.

If your certificate came with intermediate CA certificates, you may need to save them on your system (/etc/ssl/certs is recommended for Debian and Ubuntu systems) and configure that file in Apache as well with:

    SSLCertificateChainFile /etc/ssl/certs/<chain-name>.pem

replacing <chain-name> with something documenting the intermediate CA certificate chain stored in that file. As above, this may end in .crt instead of .pem; Apache won't care.

LDAP Configuration

If you want to do more than determine the user's identity, such as use privgroups (workgroups) to control access to resources or obtain additional information about authenticated users such as their full name and e-mail address, you will need permissions to query the Stanford LDAP servers and additional configuration to enable the mod_webauthldap module.

First, any access to the LDAP servers (at least for purposes relevant to WebAuth) requires university approval. There are, at present, no exceptions. For this approval process, see:

<https://itservices.stanford.edu/service/directory/access/requesting>

and follow the sidebar links. To use workgroups to control access, you generally want the set of permissions called WebAuth General. The principal for which you should request access is the webauth principal for your system that you created above in the Keytab instructions.

Once you've been granted access, configure mod_webauthldap. For Debian and Ubuntu systems, add:

    WebAuthLdapHost ldap.stanford.edu
    WebAuthLdapBase cn=people,dc=stanford,dc=edu
    WebAuthLdapAuthorizationAttribute suPrivilegeGroup

to /etc/apache2/conf.d/stanford-webauth and run a2enmod webauthldap. For Red Hat Enterprise Linux 4 or 5 (or equivalent) systems, add those same lines to /etc/httpd/conf.d/stanford-webauth.conf.

For other systems, such as systems where one has built Apache and WebAuth by hand, copy conf/stanford-ldap.conf from the WebAuth source tree into your Apache 2.x conf directory and then add the line:

    Include conf/stanford-ldap.conf

in the Apache httpd.conf file. This file assumes that the WebAuth module is installed in /usr/local/libexec/apache2/modules. You will need to change the LoadModule line in that file if it's installed in some other path. If you have moved the path to the keytab, you will need to also change the WebAuthLdapKeytab directive in this file.

Multifactor (Two-Step) Authentication

Two-step authentication is a term used internally at Stanford. The WebAuth documentation instead refers to multifactor authentication. These are both the same thing; two-step authentication is Stanford's implementation of multifactor authentication. The WebAuth documentation always refers to this as multifactor, so this section will as well for consistency.

Multifactor authentication is a mechanism by which you can require the user to present more than one "factor" to be authenticated: "something the user knows" (a username and password) as well as "something the user has" (an authentication code, generated from some source like a smartphone).

Protecting a resource with multifactor is as simple as setting up one of the WebAuthRequireInitialFactor, WebAuthRequireLOA or WebAuthRequireSessionFactor directive for the resource in question. The selected directive can be placed anywhere the Require directive may be used (such as within a <Location> block, a <Directory> block, or an .htaccess file).

Authentication Factors

The following authentication factors are in use at Stanford and can be required for access to WebAuth-protected sites:

    p       Traditional username and password authentication
    o       Some multifactor authentication method was used
    o1      Multifactor authentication with a printed list
    o2      Multifactor authentication via SMS message
    o3      Multifactor authentication using a smartphone

The multifactor authentication mechanisms are listed in order of increasing security and preference. We recommend users use the smartphone multifactor authentication method whenever possible.

Two additional authentication factors are possible as session authentication factors, but will not appear as initial authentication factors:

    c       Single sign-on cookie obtained earlier that session
    k       Kerberos authentication via Negotiate-Auth

Normally, it doesn't make sense to require either of these factors, but they will appear in the factor lists in environment variables.

You will also see the following "synthetic" factors, which indicate other information about the user's authentication method:

    m       Two separate authentication methods used (password and code)
    rm      User could have been prompted for multifactor but wasn't

Usually these are the factors that you'll want to require using the WebAuth directives rather than the more specific authentication factors.

WebAuthRequireInitialFactor Directive

When multifactor is configured with this directive, the user's authentication is good for the lifetime of their session, once they successfully log in using multifactor.

Stanford's recommended setup is to add:

    WebAuthRequireInitialFactor rm

to the resource that you wish to protect. With multifactor configured in this way, WebAuth will only request a second factor from users who have set up multifactor for themselves. It will also challenge the user for a second factor at random intervals rather than on every login.

If you would rather require multifactor challenges every time a user attempts to authenticate to your site (rather than randomly requiring it), you may instead protect your resource with:

    WebAuthRequireInitialFactor m

This will prevent a user who has not set up their multifactor from accessing the resource.

    WebAuthRequireSessionFactor

When multifactor is configured with this directive, the user will be required to re-authenticate via multifactor when visiting the protected resource, regardless of whether the user's session already contains a successful and unexpired multifactor authentication. The syntax for WebAuthRequireSessionFactor is identical to that of WebAuthRequireInitialFactor, so adding

    WebAuthRequireSessionFactor rm

to a protected resource will randomly force users to re-authenticate using multifactor. This is similar to WebAuthForceLogin, except more flexible.

WebAuthRequireLOA Directive

Level of Assurance represents the confidence that WebAuth has in the identity of the user currently authenticating to it and can be used instead of requiring initial factors. Unless you have specific regulatory requirements which require you to meet a certain Level of Assurance (LOA), you can most likely skip this section.

The levels of assurance that you can require to access a given resource range from Level 1 (little or no confidence in the asserted identity's validity) to Level 4 (very high confidence in the asserted identity's validity). Two-step authentication at Stanford can provide up to an LOA of 3. The levels used at Stanford attempt to align with the Level of Assurance definitions produced by NIST, with some minor changes for Stanford's specific circumstances. See NIST Special Publication 800-63 at:

<http://csrc.nist.gov/publications/nistpubs/800-63-1/SP-800-63-1.pdf>

Level 1 requires almost no confidence in the asserted identity. It can be achieved with password challenge and any multifactor method. Sponsored accounts are restricted to a maximum LOA of 1 since Stanford does not verify the identity of holders of sponsored accounts against a government-issued photo ID or similar document. Currently, an LOA of 1 still requires using some form of multifactor authentication, but this will probably be relaxed in the future. At present, requiring an LOA of 1 is equivalent to requiring an initial factor of "m", but using "WebAuthRequireInitialFactor m" instead is simpler and recommended since it's less ambiguous.

An LOA of 2 requires a good degree of confidence that the identity as asserted is accurate. This level can only be reached by using a multifactor mechanism in addition to the traditional password challenge, and the user's account cannot be sponsored. You can require an LOA of 2 by including this directive:

    WebAuthRequireLOA 2

in the block or .htaccess file protecting the indicated resource.

An LOA of 3 requires high confidence that the identity as asserted is accurate. It requires use of a cryptographic token in addition to the traditional password challenge. As implemented at Stanford, this can only be achieved using Google Authenticator on a smartphone (iOS or Android) and the account cannot be sponsored. You can require an LOA of 3 by including this directive:

    WebAuthRequireLOA 3

in the block or .htaccess file protecting the indicated resource.

Multifactor Environmental Variables

WEBAUTH_FACTORS_INITIAL is set when the user authenticates. It contains the factors the user authenticated with as a comma-separated list. Please see the mod_webauth manual for information about the factors.

WEBAUTH_FACTORS_SESSION contains the factors the user used to authenticate to this particular site (as opposed to the factors used to authenticate the user for the first time in this session). It will be the same as WEBAUTH_FACTORS_INITIAL if the user just authenticated to the WebLogin server for the first time in this session; otherwise, it may be something weaker (such as "c", which indicates the user authenticated with a single sign-on cookie established earlier in that browser session).

TESTING

For testing instructions, see the sections Basic Testing and RUNNING THE TEST SUITE in the standard install instructions.

LICENSE

Copyright 2010, 2011, 2012, 2013

The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Converted to XHTML by faq2html version 1.36