pam_webauth_otp

(OTP PAM module for WebAuth user information service)

SYNOPSIS

  auth  required  pam_webauth_otp.so

DESCRIPTION

WebAuth is a site-wide web authentication system that uses a central login server. That login server supports multifactor authentication (and other features) via a user information service provided by the local site. OTP-based multifactor authentication is validated by WebAuth via calls to the validate function in that user information service.

pam_webauth_otp is a PAM authentication module that performs the same API calls as the WebAuth login server, allowing the same infrastructure and OTP database to be used to secure authentications that use PAM. The user is prompted for an OTP code, which is then validated by a call to the validate function of a WebAuth user information service. Any middleware that speaks the WebAuth user information service protocol can be used, whether or not it is also used for a WebAuth deployment.

This module currently only supports OTP mechanisms where the user can supply a code without any further interaction. SMS, which requires a call to send the SMS message before prompting the user, is not currently supported.

pam_webauth_otp only provides the authentication API and should only be put in the auth stack. It is not meaningful for the other PAM stacks. It is normally used in conjunction with another required module to provide multifactor authentication.

CONFIGURATION

pam_webauth_otp supports the following configuration options, which may be set in the PAM configuration as arguments listed after pam_webauth_otp.so or (if the module was built with Kerberos support) in the system krb5.conf.

To set an option that takes an argument in the PAM configuration, follow the option name with an equal sign (=) and the value, with no separating whitespace. Whitespace in option arguments is not supported in the PAM configuration files of most PAM implementations.

To set an option for the PAM module in the system krb5.conf file, put that option in the [appdefaults] section. pam_webauth_otp will look for options either at the top level of the [appdefaults] section or in a subsection named pam-webauth-otp. Currently, realm-specific configuration is not checked. For example, the following fragment of a krb5.conf file would set host to userinfo.example.com and command to webkdc:

    [appdefaults]
        pam-webauth-otp = {
            host    = userinfo.example.com
            command = webkdc
        }

There is no difference to the PAM module whether options are specified at the top level or in a pam-webauth-otp section, but always using that section is recommended since the options are otherwise rather generic and may interfere with other programs. For more information on the syntax of krb5.conf, see krb5.conf(5).

If the same option is set in krb5.conf and in the PAM configuration, the latter takes precedent.

command=command

Sets the command prefix used when making user information service calls. This should be the same string as the final component of the URL set in the mod_webkdc WebKdcUserInfoURL Apache directive. It is sent as the command portion of the remctl call. This option must be set.

host=hostname

The hostname of the WebAuth information service against which to validate the OTP code. This host, at least currently, must provide the WebAuth user information service (at least the webkdc-validate command) via remctl. The principal used for authentication will default host principal for that host, as determined by remctl's normal principal derivation algorithm, but see principal. This option must be set.

identity=principal

Sets the identity of the WebAuth user information service. This is the principal to which the module will authenticate when validating OTP codes. The default is the normal host principal for the host on which the WebAuth user information service is running.

keytab=path

Use the specified keytab to authenticate to the WebAuth information service. The first principal found in the keytab will be used as the client identity. The default, if not set, is /etc/krb5.keytab, which will generally use the local system host credentials.

port=port

The port of the WebAuth user information service. The default, if not set, is to follow the normal remctl behavior of trying the registered (4373) and legacy (4444) ports.

timeout=timeout

How long to wait, in seconds, for a reply from the WebAuth user information service before giving up and failing the authentication. This should generally be less than 60 seconds, since many PAM applications will time out themselves if a PAM authentication takes longer than that. The default, if not set, is 30 seconds.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

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

SEE ALSO

krb5.conf(5), remctl(1)

The current version of this PAM module is available from its web page at <http://www.eyrie.org/~eagle/software/pam-webauth-otp/>.

Last spun 2014-08-10 from POD modified 2014-08-03