mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-05 10:08:56 +00:00
85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# AuthInfo Object
|
|
|
|
{{since('2026.03.04-bb93ecb1')}}
|
|
|
|
AuthInfo Objects are used to represent the authentication state of a session.
|
|
There are two main ways that you might interact with them in KumoMTA:
|
|
|
|
* When performing ad-hoc authorization checks via [kumo.aaa.query_resource_access](query_resource_access.md)
|
|
* When handling authentication checks via [smtp_server_auth_plain](../events/smtp_server_auth_plain.md) or [http_server_validate_auth_basic](../events/http_server_validate_auth_basic.md).
|
|
|
|
## AuthInfo fields
|
|
|
|
The following fields may be present in an AuthInfo object:
|
|
|
|
* `identities` - an array style table listing each authenticated identity. An identity is itself an object of the form `{identity = 'username', context = 'GenericAuth'}` where the context describes where the credential came from. Context can be one of the following values:
|
|
* `SmtpAuthPlainAuthorization` - the identity came from the SMTP AUTH PLAIN `authz` field, the authorization identity.
|
|
* `SmtpAuthPlainAuthentication` - the identity came from the SMTP AUTH PLAIN `authc` field, the authenticated identity.
|
|
* `HttpBasicAuth` - the identity came from an HTTP Basic auth header
|
|
* `BearerToken` - the identity came from an HTTP Bearer token
|
|
* `ProxyAuthRfc1929` - the identity came from a SOCKS 5 RFC 1929 authentication packet
|
|
* `LocalSystem` - a special identity representing the system itself
|
|
* `GenericAuth` - the identity was produced by some generic authentication processing/handling and doesn't provide any additional context on the provenance of the authenticated identity
|
|
* `groups` - an array style table listing each group name to which the session belongs
|
|
* `peer_address` - an optional string representing the ip address of the connected peer
|
|
|
|
## Constructing an AuthInfo
|
|
|
|
When implementing [smtp_server_auth_plain](../events/smtp_server_auth_plain.md)
|
|
or [http_server_validate_auth_basic](../events/http_server_validate_auth_basic.md),
|
|
you may optionally return an `AuthInfo` object representing the overall
|
|
identity and 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)
|
|
|
|
kumo.on('http_server_validate_auth_basic', function(user, password)
|
|
local entry = password_database[user]
|
|
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 = user, context = 'HttpBasicAuth' },
|
|
},
|
|
groups = entry.groups,
|
|
}
|
|
end)
|
|
```
|