Description

Linux-pam (Pluggable Authentication Modules) is responsible for handling
authentication requests in a flexible way from linux applications, such as
login. This is a minimal pam-module implementation written in C which performs
authentication through HTTP.

The purpose for developing this pam-module is to dispatch the authentication
procedure to a remote party, and keep options open of how authentication
actually is performed. Compare with options like kerberos, ldap, pam_*sql,
which is both higly coupled to a specific implemetation and complicated to
install & configure.

By using a simple HTTP POST request the authentication api is standardized and
independent of the underlying implementation and scheme. A mutual trust between
server and pam-client is establish using ssl server & client certificates. The
remote party (authentication server) could use ldap, password-database or
enables usage of other authentication schemes such as OpenID and Webauthn
only intended for web services.

This pam-plugin is built for usage with a webauth server using OpenID (from
Google or others) for authentication instead of promting for passwords.

See more @ https://github.com/1nfiniteloop/webauth.

Build

1. Create build-environment with
   docker build --tag=pam-http-builder:1.0.0 .devcontainer/.
2. Build pam_http

   docker run \
      --rm \
      --workdir=/home/build \
      --volume=$(pwd):/home/build \
      --name=pam-http-builder \
      --user=$(id -u):$(id -g) \
      pam-http-builder:1.0.0 \
      /bin/bash -c 'mkdir build && cd build && cmake .. && make package'

Install

Install pam_http from the debian package:
sudo dpkg -i build/pam-http-1.0.0-Linux.deb

Configuration

Each Linux utility which need authentication and uses pam have a configuration
file in /etc/pam.d. Example su has its own configuration file named
accordingly, same as for login, sudo, passwd etc. A pam-module consists
of four different services; auth, session, account, password which always is
present in each configuration file.
See more @ http://www.linux-pam.org/Linux-PAM-html/sag-configuration-file.html

This module implements only the auth service, this is the only service you
need to reconfigure. Below is an example for /etc/pam.d/login. You might place
the pam-http configuration just above the common-auth include or optionally
inside /etc/pam.d/common-auth, at the top.

...
# Custom http authentication
auth     [success=done perm_denied=die new_authtok_reqd=done default=ignore]     pam_http.so url=https://auth-server.com:443/api/auth cert-path=/etc/pam-http.d/ssl key=client.key.pem cert=client.cert.pem cacert=ca-chain.cert.pem
# Standard Un*x authentication.
@include common-auth
...

The options within the brackets above means:

• success=done a successfull auth request will return success to the
  application, without calling any further modules in the stack.
• default=ignore errors such as connectivity issues, outdated certificate
  falls back to unix passwd authentication.
• perm_denied=die stops evaluation of further modules in the pam-stack when
  “401 - Permission Denied” is returned from the auth-server. Except for this
  item it’s equivalent to replace the entire bracket with the
  keyword sufficient.

Available command-line options in format “key=value” are:

• timeout= optional, default 30s - Max timeout for a http request.
• url= required - Url endpoint used for authentication.
• cert-path= optional - Prefix path for certificate files below.
• cacert= optional - Bundled certificate chain used to validate the
  server certificate, containing intermediate and root certificates.
• key=, cert= optional - Client certificate.

API

The authentication is performed by sending a http POST request to a server with
parameters for username and service-name (e.g. login, sudo, su). Password is not
part of the http post request since my intention with this project is to avoid
the need for local user password promting.

The server can choose to send a 200 status code for grant authentication or 401
for deny. Other status codes are treated as errors. The pam-http module make
sure that user exists locally before sending a request.

Develop

The project is built using a docker-container as development environment, see
further in .devcontainer/Dockerfile. Tests is written in C++ for conveniece
and have further dependencies located as git submodules under folder
third_party/.

If you want to build unittests you need to first build the libraries gtest and
httpmockserver under third_party/.

1. Initialize git submodules with git submodule update --init.
2. Build gtest/gmock and httpmockserver.
3. Build pam_http with unittests using cd build && cmake -DWITH_UNITTEST=ON ..
   followed by make test_all.

Reference

Some sources of inspiration used within this project:

• http://www.linux-pam.org/Linux-PAM-html/
• https://github.com/linux-pam/linux-pam/
• https://fedetask.com/write-linux-pam-module/
• https://github.com/CyberDem0n/pam-oauth2
• https://github.com/quarxConnect/pam_oauth2