README

   1                            pam-webauth-otp 1.0
   2           (OTP PAM module for WebAuth user information service)
   3
   4                 Written by Russ Allbery <eagle@eyrie.org>
   5
   6   Copyright 2013 The Board of Trustees of the Leland Stanford Junior
   7   University.  This software is distributed under a BSD-style license.
   8   See the LICENSE file, included in this distribution, for copyright and
   9   redistribution information.
  10
  11 BLURB
  12
  13   The WebAuth web authentication system defines a user information service
  14   protocol that's used to determine what factors a given user has access
  15   to and to validate OTP codes used for authentication to the central
  16   WebLogin server.  This PAM module uses the same protocol to talk to the
  17   same WebAuth user information service when validating OTP codes for
  18   interactive PAM-based logins.  Currently, SMS is not supported, only OTP
  19   methods that don't require a multi-step user interaction.
  20
  21 DESCRIPTION
  22
  23   WebAuth is a site-wide web authentication system that uses a central
  24   login server.  That login server supports multifactor authentication
  25   (and other features) via a user information service provided by the
  26   local site.  OTP-based multifactor authentication is validated by
  27   WebAuth via calls to the validate function in that user information
  28   service.
  29
  30   pam-webauth-otp is a PAM module that performs the same API calls as the
  31   WebAuth login server, allowing the same infrastructure and OTP database
  32   to be used to secure authentications that use PAM.  The user is prompted
  33   for an OTP code, which is then validated by a call to the validate
  34   function of a WebAuth user information service.  Any middleware that
  35   speaks the WebAuth user information service protocol can be used,
  36   whether or not it is also used for a WebAuth deployment.
  37
  38   This module currently only supports OTP mechanisms where the user can
  39   supply a code without any further interaction.  SMS, which requires a
  40   call to send the SMS message before prompting the user, is not currently
  41   supported.
  42
  43 REQUIREMENTS
  44
  45   The PAM implementations on Linux, Solaris, Mac OS X, HP-UX, and AIX
  46   should theoretically work, although the module is only tested on Linux.
  47   Use on platforms with other PAM implementations, such as IRIX or the
  48   *BSDs, will require more porting and will not currently work.  Patches
  49   are welcome.
  50
  51   The module is written in C and should hopefully build on any system with
  52   an adequate PAM library that Libtool supports.
  53
  54   pam-webauth-otp requires libwebauth from WebAuth 4.5 or later.  WebAuth
  55   must be built with remctl support.
  56
  57   pam-webauth-otp can optionally read configuration from krb5.conf as well
  58   as PAM options; for this, Kerberos libraries are also required.  This
  59   functionality should work with either MIT Kerberos or Heimdal, but will
  60   probably not work on Mac OS X since the krb5_appdefault* APIs are
  61   crippled on that platform.
  62
  63   Running the complete test suite requires the remctld program be
  64   installed in /usr/sbin, /usr/local/sbin, or a directory on the builder's
  65   PATH.  In addition, Perl 5.6 or later plus the following Perl modules
  66   are required for some tests:
  67
  68       Test::More (included with Perl 5.8 and later)
  69       Test::Pod
  70       Test::Spelling
  71
  72   All are available on CPAN.  Those tests will be skipped if the modules
  73   are not available.
  74
  75   To enable tests that may be sensitive to the local environment or that
  76   produce a lot of false positives without uncovering many problems, set
  77   RRA_MAINTAINER_TESTS to a true value.
  78
  79 COMPILING AND INSTALLING
  80
  81   To build the module, just run:
  82
  83       ./configure
  84       make
  85
  86   Kerberos support is enabled by default if configure can find Kerberos
  87   libraries.  If your Kerberos libraries aren't installed in a location
  88   found by your compiler by default and krb5-config isn't on your PATH,
  89   use the --with-krb5=PATH option to configure.  The Kerberos libraries
  90   will then be expected in PATH/lib and the headers in PATH/include.
  91
  92   To specify a particular krb5-config script to use, either set the
  93   KRB5_CONFIG environment variable or pass it to configure like:
  94
  95       ./configure KRB5_CONFIG=/path/to/krb5-config
  96
  97   To not use krb5-config and force library probing even if there is a
  98   krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:
  99
 100       ./configure KRB5_CONFIG=/nonexistent
 101
 102   To disable Kerberos support, even if you have Kerberos libraries
 103   available, pass --without-krb5 to configure.
 104
 105   To install the module into /usr/local/lib/security and the man page into
 106   /usr/local/share/man/man5, run:
 107
 108       make install
 109
 110   You can change the installation locations with the --prefix, --mandir,
 111   and --libdir options to configure.  The module will normally be
 112   installed in a subdirectory of $libdir named security, but if --prefix
 113   is set to /usr (rather than /usr/local, the default), the module will be
 114   installed in /lib/security (or /lib32/security or /lib64/security if
 115   they exist) to match the default PAM configuration.  Alternately, you
 116   can simply copy pam_webauth_otp.so to whatever directory you use for PAM
 117   modules.  On Solaris, you will need to make the module executable.
 118
 119 TESTING
 120
 121   pam-webauth-otp comes with a test suite, which you can run after
 122   building pam-afs-session with:
 123
 124       make check
 125
 126   If a test case fails, please run the that individual test case with
 127   verbose output using:
 128
 129       tests/runtests -o <name-of-test>
 130
 131   and send me the output when reporting the problem.
 132
 133 CONFIGURING
 134
 135   Just installing the module does not enable it or change anything about
 136   your system authentication configuration.  You have to add the module to
 137   your PAM configuration in the auth group, and you will also need to
 138   provide the minimum amount of configuration for it to contact the
 139   WebAuth user information service.  You will at least need to specify
 140   the server on which that service runs and the command prefix to use.
 141
 142   For Linux, this will mean a line like:
 143
 144       auth required pam_webauth_otp.so server=userinfo.example.com \
 145           command=webkdc
 146
 147   in the relevant PAM configuration file (all on one line), replacing the
 148   server parameter with your WebAuth information server host and the
 149   command with the remctl command that you use for user information
 150   service calls.
 151
 152   To affect every login on the system, Debian uses /etc/pam.d/common-auth
 153   and Red Hat uses /etc/pam.d/system-auth.  Other distributions may use
 154   other files.  You can also, obviously, use more complex configurations
 155   if you want OTP to be optional or requested only in combination with
 156   other forms of authentication.
 157
 158   For Solaris, add:
 159
 160       login auth required /usr/local/lib/security/pam_webauth_otp.so \
 161           server=userinfo.example.com command=webkdc
 162
 163   to /etc/pam.conf to affect most services, replacing the server and
 164   command parameters as above.  As with Linux, you may want a different
 165   configuration to use the module with specific services other than login
 166   (ssh for instance).
 167
 168   On all platforms, options can be put after the module name in the PAM
 169   configuration file.  This is useful if you don't have Kerberos libraries
 170   available or if you want different configurations for different
 171   services.
 172
 173   If Kerberos support was enabled, configuration options may also be put
 174   in the krb5.conf file used by your Kerberos libraries (usually
 175   /etc/krb5.conf or /usr/local/etc/krb5.conf) instead or in addition to
 176   the PAM configuration.  See the man page for more details.  This is
 177   recommended for general system configuration, since the krb5.conf
 178   configuration syntax is a little nicer and more flexible.
 179
 180   If you are using this module with ssh, be aware that it requires
 181   ChallengeResponseAuthentication (keyboard-interactive).  It will not
 182   work with the simpler PasswordAuthentication (password) protocol because
 183   it is prompting for an OTP code, not a password, and doesn't reuse the
 184   same password as other PAM modules.  Thankfully, most ssh clients now
 185   support keyboard-interactive.
 186
 187 SUPPORT
 188
 189   The pam-webauth-otp web page at:
 190
 191       http://www.eyrie.org/~eagle/software/pam-webauth-otp/
 192
 193   will always have the current version of this package, the current
 194   documentation, and pointers to any additional resources.
 195
 196   New releases are announced via the low-volume webauth-announce mailing
 197   list.  To subscribe or see the list archives, go to:
 198
 199       https://mailman.stanford.edu/mailman/listinfo/webauth-announce
 200
 201   There is also a separate mailing list for general discussion and
 202   requests for help with WebAuth, and this PAM module can be discussed
 203   there.  To subscribe or see the list archives, go to:
 204
 205       https://mailman.stanford.edu/mailman/listinfo/webauth-info
 206
 207   For Stanford affiliates, this PAM module is a supported product of the
 208   ITS Infrastructure Delivery Group.  You can report problems or request
 209   help with WebAuth by submitting a HelpSU ticket at:
 210
 211       <https://helpsu.stanford.edu/helpsu/3.0/helpsu>
 212
 213   For non-Stanford users, please instead subscribe to webauth-info and ask
 214   your question there.  We cannot provide any formal support for
 215   non-Stanford users, nor do we make any promises or committments related
 216   to this software.  Please feel free to use it on an as-is basis, and
 217   please do feel free to send us any patches or improvements that you wish
 218   to contribute and we will evaluate them for future releases.  However,
 219   please be aware that our primary focus is supporting the needs of
 220   Stanford University and work on features not used by Stanford is mostly
 221   done on a volunteer basis.
 222
 223 SOURCE REPOSITORY
 224
 225   pam-webauth-otp is maintained using Git.  You can access the current
 226   source by cloning the repository at:
 227
 228       git://git.eyrie.org/kerberos/pam-webauth-otp.git
 229
 230   or view the repository via the web at:
 231
 232       http://git.eyrie.org/?p=kerberos/pam-webauth-otp.git
 233
 234   When contributing modifications, patches (possibly generated by
 235   git-format-patch) are preferred to Git pull requests.
 236
 237 LICENSE
 238
 239   The pam-webauth-otp package as a whole covered by the following
 240   copyright statement and license:
 241
 242     Copyright 2013
 243         The Board of Trustees of the Leland Stanford Junior University
 244
 245     Permission is hereby granted, free of charge, to any person obtaining
 246     a copy of this software and associated documentation files (the
 247     "Software"), to deal in the Software without restriction, including
 248     without limitation the rights to use, copy, modify, merge, publish,
 249     distribute, sublicense, and/or sell copies of the Software, and to
 250     permit persons to whom the Software is furnished to do so, subject to
 251     the following conditions:
 252
 253     The above copyright notice and this permission notice shall be
 254     included in all copies or substantial portions of the Software.
 255
 256     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 257     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 258     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 259     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 260     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 261     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 262     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 263
 264   All individual files without an explicit exception below are released
 265   under this license.  Some files may have additional copyright holders as
 266   noted in those files.  There is detailed information about the licensing
 267   of each file in the LICENSE file in this distribution.
 268
 269   Some files in this distribution are individually released under
 270   different licenses, all of which are compatible with the above general
 271   package license but which may require preservation of additional
 272   notices.  All required notices are preserved in the LICENSE file.