Using PAM authentication

maddy supports user authentication using PAM infrastructure via auth.pam module.

In order to use it, however, either maddy itself should be compiled with libpam support or a helper executable should be built and installed into an appropriate directory.

It is recommended to use builtin libpam support if you are using PAM as an intermediate for authentication provider not directly supported by maddy.

If PAM authentication requires privileged access on the host system (e.g. pam_unix.so aka /etc/shadow) then it is recommended to use a privileged helper executable since maddy process itself won't have access to it.

Built-in PAM support

Binary artifacts provided for releases do not come with libpam support. You should build maddy from source.

See here for detailed instructions.

You should have libpam development files installed (libpam-dev package on Ubuntu/Debian).

Then add --tags 'libpam' to the build command:

./build.sh --tags 'libpam'

Then you should be able to replace local_authdb implementation in default configuration with auth.pam:

auth.pam local_authdb {
    use_helper no
}

Helper executable

TL;DR

git clone https://github.com/foxcpp/maddy
cd maddy/cmd/maddy-pam-helper
gcc pam.c main.c -lpam -o maddy-pam-helper

Copy the resulting executable into /usr/lib/maddy/ and make it setuid-root so it can read /etc/shadow (if that's necessary):

chown root:maddy /usr/lib/maddy/maddy-pam-helper
chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper

Then you should be able to replace local_authdb implementation in default configuration with auth.pam:

auth.pam local_authdb {
    use_helper yes
}

Account names

Since PAM does not use emails for authentication you should also configure storage backend to use username only as an account identifier, not full email addresses:

storage.imapsql local_mailboxes {
    ...
    delivery_map email_localpart
    auth_normalize precis_casefold
}

This way, when authenticating as foxcpp, it will be mapped to foxcpp storage account. E.g. you will need to run maddy imap-accts create foxcpp, without the domain part.

If you have existing accounts, you will need to rename them.

Change to auth_normalize is necessary so that normalization function will not attempt to parse authentication identity as a email.

When a email is received, delivery_map email_localpart will strip the domain part before looking up the account. That is, foxcpp@example.org will be become just foxcpp.

You also need to make authorize_sender check (used in submission endpoint) accept non-email usernames:

authorize_sender {
  ...
  auth_normalize precis_casefold
  user_to_email regexp "(.*)" "$1@$(primary_domain)"
}

Note that is would work only if clients use only one domain as sender ($(primary_domain)). If you want to allow sending from all domains, you need to remove authorize_sender check altogether since it is not currently supported.

PAM service

You should create a PAM configuration file for maddy to use. Place it into /etc/pam.d/maddy. Here is the minimal example using pam_unix (shadow database).

#%PAM-1.0
auth    required    pam_unix.so
account required    pam_unix.so

Here is the configuration example you could use on Ubuntu to use the authentication config system itself uses:

#%PAM-1.0

@include common-auth
@include common-account
@include common-session