PAM
You can find the PAM authentication plugin here.
Installation
libcurl >= 7.19.1 and libpam development headers are required to compile the plugin. In the future, the C library will be used instead of CURL.
Run:
$ make # make install
to compile pam_restauth.so and copy it to /lib/security/, where PAM modules reside by default.
Usage
To use the plugin, add it to the corresponding file in /etc/pam.d/, depending on where you want to enable RestAuth authentication on your system. See the manual for pam.d(5) for details or the examples section below. At the moment, the plugin supports the following options:
- url=<url> (required) The URL of the RestAuth provider.
- service_user=<username> (required) The username used to authenticate as a service.
- service_password=<password> (required) The password used to authenticate as a service.
- group=<group name> (optional, NOT IMPLEMENTED YET) A group the user has to belong to in order for authentication to succeed.
- validate_certificate=yes/no (optional, defaults to yes) Do (not) attempt to validate the SSL certificate of the RestAuth provider. If the connection to the server is done via SSL and, for some reason, you don't want to check the certificate, set this to no. Ideally, you should create a self-signed certificate and trust it on the RestAuth server instead of using this option, in case you don't have access to an already-trusted CA. Otherwise, you won't be able to guarantee the authenticity of the server and you may be the victim of a Man-in-the-middle attack. In other words, never use this option!
The options can be specified in any order. If you need to use spaces in options (e.g. for usernames with spaces), surround the affected option with square brackets. See the manual for pam.d(5) for specifics.
Examples
In the examples, we assume that a service with username "vowi" and password "vowi" exists; our example RestAuth provider is located at http://localhost:8000/.
Your system's PAM configuration can vary by distribution. You will usually find the configuration files in /etc/pam.d/. Some distributions, like Ubuntu, have their own file structure in /etc/pam.d and extra scripts to manage aspects of PAM configuration (like pam-auth-update(8)). Generally however, each program (like login, gnome-screensaver, ...) has its own configuration file in /etc/pam.d/ where you can manage per-program PAM settings.
- To allow users from group "tomato" (WARNING: GROUP CHECK NOT IMPLEMENTED YET!) to login on a machine using RestAuth in addition to anything else (e.g. local password), add the following to the beginning of /etc/pam.d/login:
auth sufficient pam_restauth.so url=http://localhost:8000/ service_user=vowi service_password=vowi group=tomato
- To allow all users known to the RestAuth server (and noone else) to authenticate to the Dovecot IMAP server, replace the contents of /etc/pam.d/dovecot with:
auth required pam_restauth.so url=http://localhost:8000/ service_user=vowi service_password=vowi
Remember that line order in PAM configuration files is important. For the difference between "sufficient" and "required", also best read the pam.d(5) manual page.
License
The PAM plugin is licensed under the GPLv3.
Missing features
- Group check
- Integration with the C library
- Matching between Unix and RestAuth groups
- Creation of user accounts with a certain UID on first login; matching between Unix and RestAuth properties (full name, etc.)