Description

A PAM authentication module, providing a VFS_auth subclass able to use a VFS server's local PAM configuration against provided credentials.

This module requires pam-devel.

Centos Install

yum install pam-devel

Ubuntu Install

apt-get install libpam0g-dev

Installation

The posix/unix username, userid, groups, and full name will be retrieved from the resources provided by the machine running the VFS executable. This includes LDAP, OAuth2, or whatever other PAM modules are enabled on the host machine.

It's nice to present a user's real name in the interface as needed, which can be set for each user using the GECOS field:

sudo useradd -m jdoe
sudo passwd jdoe
sudo chfn -f "John Doe" jdoe

For Linux:

The user running the VFS will need to be able to verify a user's credentials, which means that it will need to be able to call unix_chkpwd from within PAM. The /sbin/unix_chkpwd command will not run on its own, but will be called from pam during authentication. The simple way to make this call successful is to add the user running the VFS to the shadow group:

sudo usermod -a -G shadow vfs_user

If you don't want to grant access to /etc/shadow, you could use the pam_localuser module.

For advanced configurations you will want to create a service file in /etc/pam.d/service_name, and provide the service_name in config.xml. The default service_name is VFS_pam if none is provided. The service file is optional, but allows for more fine-grained control of authentication. If a service name is specified but a matching service file is not found, it will still use the normal login checks, however it is recommended that you link or copy the example vfs_pam file or create your own, because most unix installations will include a faildelay setting of around 3 seconds by default. The plugin is single-threaded, so a failed authentication request will block that thread for faildelay microseconds, which will prevent other users from logging in during that time.

Note that the service can be named anything you want, but the service file in /etc/pam.d must be the lowercase name of that service.

Of particular note is the pam_listfile module, which can create an exclude/include mechanism for particular users by name, which could be added to a custom service name rule file in /etc/pam.d.

An example service file is provided in the examples folder. This can be softlinked into /etc/pam.d:

sudo ln -s /path/to/VFS_pam/examples/vfs_pam_linux /etc/pam.d/vfs_pam

For OSX:

The service file is required, because by default an application will not be able to reach out to OpenDirectory for authentication. An example is provided:

sudo ln -s /path/to/VFS_pam/examples/vfs_pam_osx /etc/pam.d/vfs_pam

Haven't figured out how to shorten the faildelay in OpenDirectory, as pam_fail_delay() is not a function, and pam_opendirectory.so does not accept a delay parameter.

Debugging

It's super helpful to tail -f /var/log/auth.log or tail -f /var/log/secure or similar to see where PAM is rejecting an authentication. On osx you can open the console.app and filter by VFS.

For instance, during development I added my current user to the shadow group, but the user isn't actually in that group until a new shell is created. Groups can be checked using the groups command. If you have many terminals open it can be confusing why it works in a new shell but not in a stale shell that has been sitting open. The tail of /var/log/auth.log reports "user unknown" when authenticating a user that is not the same as the user running VFS because that user (in the shell context it's in) isn't a member of shadow and therefore can't query /etc/shadow, and therefore has no knowledge of any users except its own.