Dovecot Lua integration
With some Lua glue in Dovecot, it is possible to connect the service directly to Nauthilus. Starting with Dovecot 2.3.19 there exists a HTTP client which can be used to communicate seamlessly with nauthilus.
Here is a real life example on how to achieve this. The mail system is using LDAP with a site-specific mail schema.
The schema is not published; the attribute names starting with rnsMS in the code below are placeholders for the
attributes of your own directory (quota, over-quota flag, mail location, master-user marker). Upon successful login,
some extra fields are returned for the userdb backend.
The matching Nauthilus configuration is shown in Nauthilus configuration below.
Nauthilus is TLS encrypted and requires HTTP basic authentication. The credentials are read from a file. You can create one like this:
echo -n "username:password" | base64 > http-auth.secret
chmod 640 http-auth.secret
chown root:vmail http-auth.secret
The Lua code (requires lua-cjson support):
--
-- START settings
--
local http_debug = false;
local http_basicauthfile = "/etc/dovecot/http-auth.secret"
local http_uri = "https://login.example.com/api/v1/auth/json"
local http_access_denied = "Account not enabled"
--
-- END settings
--
local json = require('cjson')
local PASSDB = "passdb"
local USERDB = "userdb"
-- HTTP defaults
local http_basicauthpassword
local http_client = dovecot.http.client{
timeout = 300;
max_attempts = 3;
debug = http_debug;
user_agent = "Dovecot/2.3";
}
local function init_http()
-- Read Nauthilus password
local file = assert (io.open(http_basicauthfile))
http_basicauthpassword = file:read("*all")
file:close()
end
local function query_db(request, password, dbtype)
local remote_ip = request.remote_ip
local remote_port = request.remote_port
local local_ip = request.local_ip
local local_port = request.local_port
local client_id = request.client_id
local qs_noauth = ""
local extra_fields = {}
local function add_extra_field(pf, key, value)
if value ~= nil and value:len()>0 then
extra_fields[pf .. key] = value
end
end
if dbtype == USERDB then
qs_noauth = "?mode=no-auth"
end
local auth_request = http_client:request {
url = http_uri .. qs_noauth;
method = "POST";
}
-- Basic Authorization
auth_request:add_header("Authorization", "Basic " .. http_basicauthpassword)
-- Set CT
auth_request:add_header("Content-Type", "application/json")
if remote_ip == nil then
remote_ip = "127.0.0.1"
end
if remote_port == nil then
remote_port = "0"
end
if local_ip == nil then
local_ip = "127.0.0.1"
end
if local_port == nil then
local_port = "0"
end
if client_id == nil then
client_id = ""
end
if dbtype == PASSDB then
-- Master user: change passdb-query to userdb-query
if request.auth_user:lower() ~= request.user:lower() then
add_extra_field("", "user", request.user)
local userdb_status = query_db(request, "", USERDB)
if userdb_status == dovecot.auth.USERDB_RESULT_USER_UNKNOWN then
return dovecot.auth.PASSDB_RESULT_USER_UNKNOWN, ""
elseif userdb_status == dovecot.auth.USERDB_RESULT_INTERNAL_FAILURE then
return dovecot.auth.PASSDB_RESULT_INTERNAL_FAILURE, ""
else
return dovecot.auth.PASSDB_RESULT_OK, extra_fields
end
end
end
local req = {}
req.username = request.user
req.password = password
req.client_ip = remote_ip
req.client_port = remote_port
req.client_id = client_id
req.local_ip = local_ip
req.local_port = local_port
req.protocol = request.service
req.method = request.mech:lower()
if request.secured == "TLS" or request.secured == "secured" then
req.ssl = "1"
req.ssl_protocol = request.secured
if request.cert ~= "" then
req.ssl_client_verify = "1"
end
end
if request.session ~= nil then
auth_request:add_header("X-Dovecot-Session", request.session)
end
auth_request:set_payload(json.encode(req))
-- Send
local auth_response = auth_request:submit()
-- Response
local auth_status_code = auth_response:status()
local auth_status_message = auth_response:header("Auth-Status")
local dovecot_account = auth_response:header("Auth-User")
local nauthilus_session = auth_response:header("X-Nauthilus-Session")
dovecot.i_info("request=" .. dbtype .. " auth_status_code=" .. tostring(auth_status_code) .. " auth_status_message=<" .. auth_status_message .. "> nauthilus_session=" .. nauthilus_session)
-- Handle valid logins
if auth_status_code == 200 then
local resp = json.decode(auth_response:payload())
local pf = ""
if dovecot_account and dovecot_account ~= "" then
add_extra_field("", "user", dovecot_account)
end
if dbtype == PASSDB then
pf = "userdb_"
end
if resp and resp.attributes then
if resp.attributes.rnsMSQuota then
add_extra_field(pf, "quota_rule=*:bytes", resp.attributes.rnsMSQuota[1])
end
if resp.attributes.rnsMSOverQuota then
add_extra_field(pf, "quota_over_flag", resp.attributes.rnsMSOverQuota[1])
end
if resp.attributes.rnsMSMailPath then
add_extra_field(pf, "mail", resp.attributes.rnsMSMailPath[1])
end
if resp.attributes["ACL-Groups"] then
add_extra_field(pf, "acl_groups", resp.attributes["ACL-Groups"][1])
end
end
if request.session then
if dbtype == PASSDB then
if resp and resp.attributes then
local proxy_host
local master_user
if resp.attributes["Proxy-Host"] then
proxy_host = resp.attributes["Proxy-Host"][1]
end
if resp.attributes.rnsMSDovecotMaster then
master_user = resp.attributes.rnsMSDovecotMaster[1]
end
-- Master users must not be proxied
if master_user and master_user == "" then
if proxy_host and proxy_host ~= "" then
extra_fields.proxy_maybe = "y"
extra_fields.proxy_timeout = "120"
extra_fields.host = proxy_host
end
end
end
end
end
if dbtype == PASSDB then
return dovecot.auth.PASSDB_RESULT_OK, extra_fields
else
return dovecot.auth.USERDB_RESULT_OK, extra_fields
end
end
-- Handle failed logins
if auth_status_code == 403 then
if dbtype == PASSDB then
if auth_status_message == http_access_denied then
return dovecot.auth.PASSDB_RESULT_USER_DISABLED, auth_status_message
end
return dovecot.auth.PASSDB_RESULT_PASSWORD_MISMATCH, auth_status_message
else
return dovecot.auth.USERDB_RESULT_USER_UNKNOWN, auth_status_message
end
end
-- Unable to communicate with Nauthilus (implies status codes 50X)
if dbtype == PASSDB then
return dovecot.auth.PASSDB_RESULT_INTERNAL_FAILURE, ""
else
return dovecot.auth.USERDB_RESULT_INTERNAL_FAILURE, ""
end
end
function auth_userdb_lookup(request)
return query_db(request, "", USERDB)
end
-- {{{
function auth_passdb_lookup(request)
_ = request
return dovecot.auth.PASSDB_RESULT_OK, "nopassword=y"
end
-- }}}
function auth_password_verify(request, password)
return query_db(request, password, PASSDB)
end
function script_init()
init_http()
return 0
end
function script_deinit()
end
function auth_userdb_iterate()
local user_accounts = {}
local list_request = http_client:request {
url = http_uri .. "?mode=list-accounts";
method = "GET";
}
-- Basic Authorization
list_request:add_header("Authorization", "Basic " .. http_basicauthpassword)
-- Set CT
list_request:add_header("Accept", "application/json")
local list_response = list_request:submit()
local resp_status = list_response:status()
if resp_status == 200 then
user_accounts = json.decode(list_response:payload())
end
return user_accounts
end
Look at the code especially to the response headers. Nauthilus is delivering all extra fields by prefixing HTTP headers with X-Nauthilus- and the name of an extra field. The result itself is JSON. Most of the time, you will use values from the attributes list. In the example above, you can see a working configuration with OpenLDAP and a site-specific schema.
Nauthilus configuration
The Dovecot script needs three things from Nauthilus: the JSON endpoint with backchannel Basic authentication, an LDAP search for the protocols that Dovecot sends, and the attributes that the script reads from the response.
runtime:
servers:
http:
address: "0.0.0.0:8080"
storage:
redis:
primary:
address: "127.0.0.1:6379"
password_nonce: "replace-with-a-random-nonce"
encryption_secret: "replace-with-a-random-secret"
auth:
backchannel:
basic_auth:
enabled: true
# The same credentials as in /etc/dovecot/http-auth.secret
username: "username"
password: "password"
backends:
order:
- "cache"
- "ldap"
ldap:
default:
server_uri:
- "ldap://ldap.example.com:389"
bind_dn: "cn=nauthilus,ou=services,dc=example,dc=com"
bind_pw: "replace-with-the-bind-password"
search:
# Dovecot sends its service name as the protocol.
- protocol:
- "imap"
- "pop3"
- "lmtp"
- "sieve"
- "doveadm"
cache_name: "dovecot"
base_dn: "ou=people,dc=example,dc=com"
filter:
# Used for password checks and for ?mode=no-auth
user: "(&(objectClass=inetOrgPerson)(uid=%L{user}))"
# Used for ?mode=list-accounts
list_accounts: "(objectClass=inetOrgPerson)"
mapping:
account_field: "uid"
# Replace the rnsMS* names with the attributes of your own schema.
attribute:
- "uid"
- "rnsMSQuota"
- "rnsMSOverQuota"
- "rnsMSMailPath"
- "rnsMSDovecotMaster"
Every attribute in the attribute list is returned in the JSON response below attributes, each as a list of values.
Proxy-Host in the Dovecot script is not an LDAP attribute; it is an attribute that a subject source adds to the
backend result with apply_backend_result.
Without such a subject source the script delivers mail locally.
http_uri in the Dovecot script points to /api/v1/auth/json on this listener. TLS for the listener and all further
keys are described in Server configuration and
LDAP backend. The OpenLDAP tutorial
contains a complete stack that you can start locally. The LDAP schema in
contrib/ldap of the Nauthilus repository only adds
the attribute for WebAuthn credentials; it is not required for this example.
Nauthilus modes
As Dovecot needs three different things like passdb, userdb and iterator, nauthilus was made compatible to deal with these requirements. By adding a query string to the HTTP request, nauthilus knows what to deliver. See the description at the endpoint page.
?mode=no-auth
This mode is used for the userdb lookup. It fetches a user and its extra fields. In this mode, no authentication is done at all.
?mode=list-accounts
This mode returns the full list of known accounts.