1# Using PAM authentication23maddy supports user authentication using PAM infrastructure via `auth.pam`4module.56In order to use it, however, either maddy itself should be compiled7with libpam support or a helper executable should be built and8installed into an appropriate directory.910It is recommended to use builtin libpam support if you are using11PAM as an intermediate for authentication provider not directly12supported by maddy.1314If PAM authentication requires privileged access on the host system15(e.g. pam_unix.so aka /etc/shadow) then it is recommended to use16a privileged helper executable since maddy process itself won't17have access to it.1819## Built-in PAM support2021Binary artifacts provided for releases do not come with22libpam support. You should build maddy from source.2324See [here](../building-from-source) for detailed instructions.2526You should have libpam development files installed (`libpam-dev`27package on Ubuntu/Debian).2829Then add `--tags 'libpam'` to the build command:30```31./build.sh --tags 'libpam'32```3334Then you should be able to replace `local_authdb` implementation35in default configuration with `auth.pam`:36```37auth.pam local_authdb {38 use_helper no39}40```4142## Helper executable4344TL;DR45```46git clone https://github.com/foxcpp/maddy47cd maddy/cmd/maddy-pam-helper48gcc pam.c main.c -lpam -o maddy-pam-helper49```5051Copy the resulting executable into /usr/lib/maddy/ and make52it setuid-root so it can read /etc/shadow (if that's necessary):53```54chown root:maddy /usr/lib/maddy/maddy-pam-helper55chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper56```5758Then you should be able to replace `local_authdb` implementation59in default configuration with `auth.pam`:60```61auth.pam local_authdb {62 use_helper yes63}64```6566## Account names6768Since PAM does not use emails for authentication you should configure69maddy to either strip domain part when checking credentials or do not70use email when authenticating.7172See [Multiple domains configuration](/multiple-domains) for how to configure73authentication.7475## PAM service7677You should create a PAM configuration file for maddy to use.78Place it into /etc/pam.d/maddy.79Here is the minimal example using pam_unix (shadow database).80```81#%PAM-1.082auth required pam_unix.so83account required pam_unix.so84```8586Here is the configuration example you could use on Ubuntu87to use the authentication config system itself uses:88```89#%PAM-1.09091@include common-auth92@include common-account93@include common-session94```