mirrors/maddy
1
0
Fork 0
mirror of https://github.com/foxcpp/maddy.git synced 2025-04-06 06:27:38 +03:00
Code Issues Projects Releases Packages Wiki Activity

docs: Improve description of how delivery_map is supposed to be used for custom authentication support

Browse source
This commit is contained in:
fox.cpp 2022-09-11 20:58:40 +03:00
parent d54237f856
commit f7107d4a92
No known key found for this signature in database
GPG key ID: 5B991F6215D2FCC0
2 changed files with 51 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

44
docs/tutorials/pam.md
View file

@ -4,7 +4,7 @@ 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
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
@ -13,7 +13,7 @@ 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
a privileged helper executable since maddy process itself won't
have access to it.
## Built-in PAM support
@ -23,7 +23,7 @@ libpam support. You should build maddy from source.
See [here](../building-from-source) for detailed instructions.
You should have libpam development files installed (`libpam-dev`
You should have libpam development files installed (`libpam-dev`
package on Ubuntu/Debian).
Then add `--tags 'libpam'` to the build command:
@ -48,9 +48,9 @@ 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
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
```
@ -66,7 +66,8 @@ auth.pam local_authdb {
## Account names
Since PAM does not use emails for authentication you should also
switch storage backend to using usernames for authentication:
configure storage backend to use username only as an account identifier,
not full email addresses:
```
storage.imapsql local_mailboxes {
...
@ -74,14 +75,39 @@ storage.imapsql local_mailboxes {
auth_normalize precis_casefold
}
```
(See [Multiple domains](../../multiple-domains) for details)
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
@ -89,7 +115,7 @@ 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