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.