mirror of
https://github.com/KumoCorp/kumomta.git
synced 2026-09-08 08:01:19 +00:00
109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# smtp_server_auth_plain
|
|
|
|
```lua
|
|
kumo.on(
|
|
'smtp_server_auth_plain',
|
|
function(authz, authc, password, conn_meta) end
|
|
)
|
|
```
|
|
|
|
Called by the ESMTP server in response to the client issuing an `"AUTH PLAIN"`
|
|
authentication attempt.
|
|
|
|
KumoMTA will only allow `AUTH PLAIN` once STARTTLS has been successfully
|
|
enabled for the session.
|
|
|
|
At the time of writing KumoMTA doesn't provide a general authentication
|
|
solution, but through the use of this callback, you have some flexibility.
|
|
|
|
The event handler receives the following parameters:
|
|
|
|
* *authz* - the *authorization identity* which the client wishes to act as
|
|
* *authc* - the *authentication identity* which identifies the client for the
|
|
purposes of validating who the client claims to be. *authc* is paired
|
|
with the *password* parameter.
|
|
* *password* - the password which belongs to the claimed *authc*
|
|
* *conn_meta* - represents the connection metadata and
|
|
can be used to share state between the various SMTP listener
|
|
event handlers. See [Connection Metadata](../connectionmeta.md)
|
|
for more information.
|
|
|
|
{{since('2023.08.22-4d895015', indent=True)}}
|
|
The *conn_metadata* parameter is new as of this release.
|
|
|
|
Note that [PLAIN SASL](https://www.rfc-editor.org/rfc/rfc4616) allows for *authz*
|
|
to be empty. KumoMTA will assume the same value as *authc* in that case, so
|
|
this event will always be triggered with that value.
|
|
|
|
The SMTP server expects the event handler to return a bool value; if it returns
|
|
true then it considers the credentials to be valid and will associated the claimed
|
|
identities with the session, and yield an SMTP `235` successful authentication
|
|
response to the client. The *authz* and *authc* parameters will be set
|
|
in the message meta object as `"authz_id"` and `"authn_id"` respectively.
|
|
|
|
If it returns false then the authentication attempt is considered to have failed
|
|
and will yield an SMTP `535` failed authentication response to the client.
|
|
|
|
This example shows how to implement a very simple inline password database
|
|
using a lua table:
|
|
|
|
```lua
|
|
-- Use this to lookup and confirm a user/password credential
|
|
kumo.on('smtp_server_auth_plain', function(authz, authc, password, conn_meta)
|
|
-- This is just an example of how to populate the return value,
|
|
-- not a recommended way to handle passwords in production!
|
|
-- In particular, it is an absolutely terrible idea to hard code
|
|
-- a password here in plain text!
|
|
local password_database = {
|
|
['daniel'] = 'tiger',
|
|
}
|
|
if password == '' then
|
|
return false
|
|
end
|
|
return password_database[authc] == password
|
|
end)
|
|
```
|
|
|
|
## Returning Group and identity Information
|
|
|
|
{{since('2026.03.04-bb93ecb1')}}
|
|
|
|
Rather than just returning a boolean to indicate whether authentication was
|
|
successful, you may now return an [AuthInfo](../kumo.aaa/auth_info.md) object
|
|
holding additional information. Here's an expanded version of the example
|
|
above that shows how you can return group membership:
|
|
|
|
```lua
|
|
-- This is just an example of how to populate the return value,
|
|
-- not a recommended way to handle passwords in production!
|
|
-- In particular, it is an absolutely terrible idea to hard code
|
|
-- a password here in plain text!
|
|
|
|
local password_database = {
|
|
['daniel'] = {
|
|
password = 'tiger',
|
|
groups = { 'group1', 'group2' },
|
|
},
|
|
}
|
|
|
|
kumo.on('smtp_server_auth_plain', function(authz, authc, password)
|
|
local entry = password_database[authc]
|
|
if not entry then
|
|
return false
|
|
end
|
|
if entry.password ~= password then
|
|
return false
|
|
end
|
|
|
|
-- Return an AuthInfo that lists out the identity and group
|
|
-- membership
|
|
return {
|
|
identities = {
|
|
{ identity = authz, context = 'SmtpAuthPlainAuthorization' },
|
|
{ identity = authc, context = 'SmtpAuthPlainAuthentication' },
|
|
},
|
|
groups = entry.groups,
|
|
}
|
|
end)
|
|
```
|