pam_sshauth
===========

pam_sshauth is a PAM library that allows you to authenticate a local machine
based on being able to ssh into a remote one.  It essentially ties a local
pam login to a remote ssh login.

Requirements:
-------------

pam_sshauth requires:

  * libssh version 4 or better

Configuration:
--------------

The pam_sshauth module understands 6 pam command line options:

  * host=<hostname.or.ip>
  * port=<port>
  * nostrict
  * authtries=<number>
  * try_first_pass
  * shm_askpass

So, in the pam file for the service you're using pam_sshauth with, you could
specify:

auth    required        pam_sshauth.so host=myhost.com port=128 nostrict

The "nostrict" option allows the pam_sshauth module, upon ssh'ing into a host
you don't currently have the host key for, to ask you, via the pam prompts
mechanism, if you'd like to add the current host to your host keys.  The
default is that this option will not be offered to you, and any attempt to
authenticate against a machine you don't have the host key for will fail.

The shm_askpass option will cause the pam module to work with the ssh ASKPASS
helper shm_askpass.

The pam_sshauth module will ALSO check for the presence of two environment
variables: PAM_SSHAUTH_HOST and PAM_SSHAUTH_PORT.  It isn't necessary on either
the pam command line OR the environment variable to set the port: it will
default to 22.  However, if neither the pam command host= parameter or the
PAM_SSHAUTH_HOST environment variable are set, the authentication will fail.

The pam_sshauth module can handle password expiry, via ssh's "kbint" (keyboard
interactive) method of authentication.  It will detect if the authentication
server's sshd supports this option.

By default, sshd comes configured with simple password authentication.  If
you'd like password expiry to work, you need to set:

ChallengeResponseAuthentication yes

in your /etc/ssh/sshd_config file on the server.

Interactions with ssh:
----------------------

One of the primary goals with pam_sshauth is to create an ssh "Master socket"
which can thereafter be used to launch programs on the remote system.  The
pam_sshauth library contains no method to do this directly, for the sake of
simplicity.  Rather, we provide a helper which can be used via the SSH-ASKPASS
mechanism, as well as an example script which can be used in conjunction with
pam_exec to create the tunnel.

The shm_askpass program is an SSH-ASKPASS compliant shell script.

In the examples directory of this archive I've provided an example session
script for use with pam_exec which will handle storing the password, launching
the ssh Master socket, and closing the socket down on pam session completion.


Testing:
--------

To test, create an example service file in /etc/pam.d.  You can use the
"pamtester" utility available at pamtester.sourceforge.net.

The service file should contain the following lines:

auth    required        pam_sshauth.so host=127.0.0.1  # or wherever
auth    required        pam_exec.so expose_authtok /usr/bin/ltsp-session
session required        pam_exec.so /usr/bin/ltsp-session

Copy the "examples/ltsp-session" file to /usr/bin, or somewhere else if you'd
prefer, and just modify the pam_exec lines above accordingly.

Build the source with:

./configure --prefix=/usr && make && sudo make install

Then, using pamtester utility:

pamtester service user authenticate open_session close_session

You should see something along the lines of:

sbalneav@eris:~$ pamtester flarp sbalneav authenticate open_session close_session
Password:
pamtester: successfully authenticated
pamtester: sucessfully opened a session
pamtester: session has successfully been closed.

pam_sshauth logs to authlog:

Jan 10 21:29:40 phobos pam_sshauth[22724]: Beginning authentication.
Jan 10 21:29:40 phobos pam_sshauth[22724]: User: scbal Host 127.0.0.1
Jan 10 21:29:40 phobos pam_sshauth[22724]: Auth method PASSWORD
Jan 10 21:29:40 phobos pam_sshauth[22724]: Auth method INTERACTIVE
Jan 10 21:29:40 phobos pam_sshauth[22724]: Performing keyboard interactive authentication
Jan 10 21:29:45 phobos sshd[22725]: Accepted keyboard-interactive/pam for scbal from 127.0.0.1 port 56984 ssh2
Jan 10 21:29:45 phobos sshd[22725]: pam_unix(sshd:session): session opened for user scbal by (uid=0)
Jan 10 21:29:45 phobos sshd[22783]: Received disconnect from 127.0.0.1: 11: Bye Bye
Jan 10 21:29:45 phobos sshd[22725]: pam_unix(sshd:session): session closed for user scbal

LICENSE
-------

pam_sshauth is licensed under the GNU GPL 2 or later license.

(C) 2010-2013 Scott Balneaves <sbalneav@ltsp.org>
