aiosmtpd provides a framework for SMTP Authentication that fully complies with RFC 4954.
aiosmtpd authentication is always activated,
but attempts to authenticate will always be rejected
authenticator parameter of
is set to a valid & working Authenticator Callback.
aiosmtpd Authentication Framework comprises several components,
who are collectivelly called the “AUTH API”.
AUTH Handler Hook¶
- async handle_AUTH(server: SMTP, session: Session, envelope: Envelope, args)¶
Called to handle
AUTHcommand, if you need custom AUTH behavior.
Most of the time, you will NOT need to implement this hook; AUTH Mechanism Hooks are provided to override/implement selective SMTP AUTH mechanisms (see below).
If you do implement this hook:
You MUST comply with RFC 4954.
argswill contain the list of words following the
You will have to leverage the
SMTP.challenge_auth()methods to interact with the clients.
You will need to modify the
You may ignore the
AUTH Mechanism Hooks¶
Separately from AUTH Handler Hook,
aiosmtpd also implement support for “AUTH Mechanism Hooks”.
These async hooks will implement the logic for SMTP Authentication Mechanisms.
Every AUTH Mechanism Hook is named
MECHANISM is the all-uppercase name of the mechanism
that the hook will implement.
(Mechanism is the word following the
AUTH command sent by client.)
MECHANISM has a dash within its name,
use double-underscore to represent the dash.
For example, to implement a
name the AUTH hook as
Single underscores will not be modified.
So a hook named
will implement the
(If in the future a SASL mechanism with double underscores in its name gets defined, this name-mangling mechanism will be revisited. That is very unlikely to happen, though.)
Alternatively, you can also use the
which you can import from the
The SMTP class provides built-in AUTH hooks for the
If the handler class implements
the methods of the handler instance will override the built-in methods.
- async auth_MECHANISM(server: SMTP, args: List[str]) aiosmtpd.smtp.AuthResult ¶
server – The instance of the
SMTPclass invoking the AUTH Mechanism hook
args – A list of string split from the characters following the
argsis usually equal to
auth_mechanism()decorator has been used).
The AUTH hook MUST perform the actual validation of AUTH credentials.
In the built-in AUTH hooks, this is done by invoking the function specified by the
AUTH Mechanism Hooks in handlers are NOT required to do the same, and MAY implement their own authenticator system.
The AUTH Mechanism Hook MUST return an instance of
AuthResultcontaining the result of the Authentication process.
Defining additional AUTH hooks in your handler
will NOT disable the built-in LOGIN and PLAIN hooks;
if you do not want to offer the LOGIN and PLAIN mechanisms,
specify them in the
- Authenticator(server, session, envelope, mechanism, auth_data) AuthResult ¶
server – The
SMTPinstance that invoked the authenticator
session – A
Sessioninstance containing session data so far
envelope – An
Envelopeinstance containing transaction data so far
mechanism (str) – name of the AUTH Mechanism chosen by the client
auth_data – A data structure containing authentication data gathered by the AUTH Mechanism
Result of authentication
- Return type:
This function would be invoked during or at the end of an Authentication Process by AUTH Mechanisms. Based on
auth_data, this function should return a decision on whether Authentication has been successful or not.
This function SHOULD NOT modify the attributes of
The type and contents of the
auth_dataparameter is wholly at the discretion of the calling AUTH Mechanism. For the built-in
PLAINMechanisms, the type of data will be
New in version 1.3.
- class AuthResult(*, success, handled, message, auth_data)¶
- handled: bool = True¶
This attribute indicates whether Authenticator Decision process (e.g., sending of status codes) have been carried out by Authenticator or not.
If set to
smtp_AUTH()will not perform additional processing and will simply exits.
Applicable only if
- message: str | None = None¶
The message to send back to client, regardless of success status.
This message will be sent as-is; as such, it MUST be prefixed with the correct SMTP Status Code and optionally, SMTP Extended Status Code.
If not given (set/kept to
smtp_AUTH()will use standard SMTP Status Code & Message.
- auth_data: Any = None¶
Optional free-form authentication data. This will be saved by
auth_datahas the attribute
session.login_dataas well. This is to cater for possible backward-compatibility requirements, where legacy handlers might be looking for
session.login_datafor some reasons.
We have taken steps to prevent leakage of sensitive information (i.e., password) through logging
by overriding the
__str__ methods of the
However, we have no control on the (logging) output of your custom hooks. Please be very careful emitting/recording AUTH information to prevent leakage.
An example is provided in