Repository files navigation

Linux-pam (Pluggable Authentication Modules) is responsible for handlingauthentication requests in a flexible way from linux applications, such aslogin. This is a minimal pam-module implementation written in C which performsauthentication through HTTP.

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

By using a simple HTTP POST request the authentication api is standardized andindependent of the underlying implementation and scheme. A mutual trust betweenserver and pam-client is establish using ssl server & client certificates. Theremote party (authentication server) could use ldap, password-database orenables usage of other authentication schemes such as OpenID and Webauthnonly intended for web services.

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

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

1. Create build-environment withdocker 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 pam_http from the debian package:sudo dpkg -i build/pam-http-1.0.0-Linux.deb

Each Linux utility which need authentication and uses pam have a configurationfile in/etc/pam.d. Examplesu has its own configuration file namedaccordingly, same as forlogin,sudo,passwd etc. A pam-module consistsof four different services; auth, session, account, password which always ispresent in each configuration file.See more @http://www.linux-pam.org/Linux-PAM-html/sag-configuration-file.html

This module implements only theauth service, this is the only service youneed to reconfigure. Below is an example for/etc/pam.d/login. You might placethe pam-http configuration just above the common-auth include or optionallyinside/etc/pam.d/common-auth, at the top.

...# Custom http authenticationauth     [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 theapplication, without calling any further modules in the stack.
• default=ignore errors such as connectivity issues, outdated certificatefalls 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 thisitem it's equivalent to replace the entire bracket with thekeywordsufficient.

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 theserver certificate, containing intermediate and root certificates.
• key=, cert=optional - Client certificate.

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

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

The project is built using a docker-container as development environment, seefurther in.devcontainer/Dockerfile. Tests is written in C++ for convenieceand have further dependencies located as git submodules under folderthird_party/.

If you want to build unittests you need to first build the libraries gtest andhttpmockserver underthird_party/.

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

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