Demo
Demo

Knowledge base

PMTA knowledge base›Block <smtp-user>›Directive§ 3.3.8.2

authentication-method

<smtp-user>

What confirms a submission login
in the configuration this is a lineauthentication-method passwordinside the block <smtp-user>
Five ways to prove that the submitter is one of your own

The line chooses how the node verifies the submitter. The default is password, that is, the password from the neighboring line.

Five values, and three of them require an encrypted connection:

password — a password. system — Linux only: the password is checked against the system’s accounts. certificate — the client presents exactly the certificate file named in tls-certificate. ca-file — the client presents any certificate that chains up to tls-ca-file; optionally with a name check as well (tls-certificate-san-or-cn). {vault}:ldap — the password is checked in LDAP through the secrets vault, and then no password is written in the configuration at all.

The two certificate methods require a TLS connection — the manual says so directly. The submitting program must support either STARTTLS or SMTPS.

LDAP has a mechanism restriction: CRAM-MD5 does not work with it, only LOGIN and PLAIN. That is, submission through some PowerMTA APIs is impossible with this method.

The main trap is choosing LDAP without noticing the mechanism restriction. CRAM-MD5 drops out; LOGIN and PLAIN remain, and both transmit the password almost in the clear — which means the connection must be encrypted, and mandatorily so, not when possible.
What the Hub does. It does not write it — it leaves the default: submission goes by a login and password the Hub generates itself. Certificate methods will be needed if a platform with mutual verification appears; LDAP — if submission logins start being created in the organization’s shared directory.
Recommended values

Five values and what each requires:

Value What is needed alongside Requires TLS
password (default) password no, but it is worth requiring
system an account in Linux no, but it is worth requiring
certificate tls-certificate with a file yes
ca-file tls-ca-file, optionally a name yes
{vault}:ldap a <vault> block; no password is written yes, and only LOGIN or PLAIN

For all five it is sensible to require encryption before authentication — require-starttls-before-auth.

The five values, the password default, the TLS requirement for the certificate methods and the LDAP mechanism restriction come from the manual (§ 3.3.8.2). The advice about requiring encryption is ours.
Example configuration
# two logins, two different verification methods
<smtp-user foo>
    password barbaz
</smtp-user>

<smtp-user bar>
    authentication-method {vault}:ldap</smtp-user>
An example from the manual. The second login has no password in the configuration at all — it is checked in LDAP through the vault. But only the LOGIN and PLAIN mechanisms will work, which means the connection must be encrypted.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Choosing LDAP for submission over CRAM-MD5

§ 3.3.8.2

What it costsThe CRAM-MD5 mechanism is incompatible with this method. A submitting program configured for it will not be able to authenticate at all — and the reason in the refusal will be unclear.
How to spot itAuthentication fails for only one platform, while it works for the rest.
How to do it rightMove the platform to LOGIN or PLAIN — and be sure to require encryption, since both mechanisms transmit the password almost in the clear.

Enabling certificate verification without encryption

§ 3.3.8.2

What it costsThe certificate and ca-file methods require a TLS connection. Without it authentication is impossible, and submission stops.
How to spot itA login with a certificate method never connects even once.
How to do it rightAllow STARTTLS in the source matched by address (allow-starttls) or set up a separate SMTPS listener.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
authentication-method <enumeration>
Values
password | system | ca-file | certificate | vault-ldap (written as a reference to the vault)
Default
password § 3.3.8.2
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<smtp-user>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <smtp-user> and applies to one login; it has no inheritance — each login is configured on its own. The encryption requirement, meanwhile, is set elsewhere — in <source> — and applies to the whole connection, before the login is given.
⇄

Related directives

4 relations

Does not work without

An external secrets vaultChecking a password via LDAP goes through the secrets vault — without a declared block it is unavailable. § 3.3.8.2

Works together with

password<smtp-user>The default method: the password set by this line next to it. § 3.3.8.1tls-certificate<smtp-user>The “certificate” method: the login is confirmed by a specific certificate file. § 3.3.8.3tls-ca-file<smtp-user>The “trusted authority” method: any certificate that chains up to the specified chain will do. § 3.3.8.4

How to check on the node
Checked by trying to authenticate with the chosen method:
printf 'EHLO test\r\nAUTH LOGIN\r\n' | openssl s_client -starttls smtp -connect localhost:25 -quiet 2>/dev/null | head -5
A prompt to enter a login means the password method is available. With the certificate methods the node expects the certificate during the TLS negotiation — and without it refuses before things get to AUTH.
◇

What else to read

3 articles

◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.◇Submission logins, plain-text passwords and per-user settingsA sender logs in with one of three methods; each login is a configuration block with a plain-text password, and that login’s named source overrides what its address would have given.◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Node security · Sender isolation
Neighboring settings of the block <smtp-user>:passwordsourcetls-ca-filetls-certificatetls-certificate-san-or-cnAll 6 directives of the block →