Lua Support
Nauthilus has Lua 5.1 support in all areas of the service. To understand the interfaces, you must first get an idea of what happens with an incoming authentication request.
Authentication workflow
An incoming authentication request first enters the brute_force check. After that it continues with the features pipeline. After that has past, it continues to process the request in a password backend. When the final result for the request was obtained, it passes filters.
Filters may change the backend result in one or the other way (accepting a formely rejected message or vice versa). This is especially useful for other remote services that can influence the authentication process.
After all this has finished, it is possible to do some post actions, which are run independent of all other steps in the whole pipeline and therefore can not influence the final result anymore.
In the following sequence diagram you can see the processing of the request in more detail.
Additional things to know
When starting the server, it is possible to call an init script, which may be used to register prometheus elements, start connection tracker or define custom redis pools. The latter is interesting, if you prefer using other redis servers for all your custom Lua scripts.
While runtime...
When an incoming authentication request is started, a Lua context is created.
All parts of a request share that common request context. Lua scripts can set arbitrary data in the context and read/delete things from there.
Lua scripts can modify the final log line by adding key-value pairs from each script.
Configuration
For the configuration, please have a look for the configuration file document.
Lua components
Each component does provide a set of global functions, constants, ... and requires a well-defined response from each request.
Every Lua script that has been configured is pre-compiled and kept in memory for future use. To make script changes, you must reload the service.
Lua libraries
Nauthilus does automatically preload Lua modules.
This is the list of modules that are currently available:
| Loader name | Description |
|---|---|
| nauthilus_mail | E-Mail functions |
| nauthilus_password | Password compare and validation functions |
| nauthilus_redis | Redis related functions |
| nauthilus_misc | Country code and sleep functions |
| nauthilus_context | Global Lua context accross all States in Nauthilus |
| nauthilus_ldap | LDAP related functions |
| nauthilus_backend | Backend related functions |
| nauthilus_http_request | HTTP request header functions |
| nauthilus_http_response | HTTP response functions (headers, status, body; Filters/Features MUST NOT send a body) |
| nauthilus_prometheus | Prometheus metrics functions |
| nauthilus_soft_whitelist | Soft whitelist functions |
| nauthilus_brute_force | Brute force prevention functions |
| nauthilus_dns | DNS related functions |
| nauthilus_cache | In-process cache functions |
| nauthilus_psnet | Network connection manager functions |
| nauthilus_opentelemetry | OpenTelemetry tracing functions |
| nauthilus_util | Common utility functions |
| glua_crypto | gluacrpyto project on Github |
| glua_http | gluahttp project on Github |
In addition to these Nauthilus-specific modules, the gopher-lua-libs collection is automatically preloaded, providing access to modules like json, yaml, time, db, tcp, and more.
Example:
local nauthilus_redis = require("nauthilus_redis")
local nauthilus_builtin_context = require("nauthilus_context")
-- Gopher-Lua-Libs
local crypto = require("crypto")
local db = require("db")
local time = require("time")
-- Glua-Crypto
local crypto = require("glua_crypto") -- provides sha1 and others...
Actions
Whenever a brute froce attack is recognized, actions may be called. The request will wait until all requests have finished. Actions are processed by a central action worker. No results are returned to the regular request, so actions in general do their own logging!
Also, features may call actions if they were triggered. The request is waiting to finish all actions by the worker process.
Features
Besides the well known features geoip, rbl, tls_encryption and relay_domains, a new feature has been integrated: lua. This feature is processed before all other features (in fact, you might replace all these features with pure Lua...). Lua-features are executed in parallel starting with v1.8.9. As soon as any feature has triggered, the request will reject the authentication process after all features have finished, and the results are aggregated.
Since version 1.8.9, Lua features and filters are executed in parallel. Nauthilus waits for all scripts to finish and then aggregates their results:
- Features: triggered=true if any script reports FEATURE_TRIGGER_YES; abort flag is set if any script requests FEATURES_ABORT_YES; the first error aborts the whole operation; the first status_message set is used.
- Filters: an action is taken if any filter requests it; backend_result attributes from multiple filters are merged (later keys overwrite earlier ones); remove-attributes are unioned; the first error aborts; the first status_message set is used. Each script runs with its own Lua state and per-script timeout. Do not rely on execution order between scripts.
Furthermore, Lua features can set a flag to bypass all built-in features.
Lua backend
A new backend has been implemented. It can be used for all features that Nauthilus currently supports: Checking passwords, running different modes (no-auth, list-accounts), adding TOTP...
The backend can accept a request or reject it. It has full access to all meta information that are delivered from the incoming request.
Filters
There may exist remote services that may be contacted after the main backend authentication proccess returned its first
result. Think of something like GeoIP service or some IP white/blacklisting. Even a request that might have authenticated
correctly may be rejected to a policy violation from such a service. Therefor filters have the power to overwrite the
result from a backend.
You can also use filters to retrieve additional information from databases or LDAP and add additional attributes to the remaining result. This is useful for setups, where Nauthilus may also take the role of a Dovecot proxy. Users may get routed to different mail stores upon successful authentication. For this, you may retrieve the current backend server list with servers that have been checked as being alive with the backend_server_monitoring feature and select nominate it for the current client request.
Filters never affect caching! This is important, because otherwise valid credentials might result in storing them in the negative password cache or vice versa for invalid credentials.
You always have to deal with the "request.authenticated" flag! If you don't care enough, you might acidentially reject legitimate authenticated users or allow bad guys.
Post actions
Post actions are actions, which run after the request hast come to its final result. Its main purpose is to start some automated things like doing statistics stuff, sending messages to operators or anything else that does not require fast instant processing.
As an example have a look at the telegram script. Lua scripts in earlier stages of the process may provide some information by using the Lua context. The telegram script may pick up these information and decide to send out some notifications to an operator channel.
Required functions and constants
Every Lua script must provide a pre-defined Lua function with a request parameter. Concerning the actual script, there is a requried return statement.
Nauthilus will look for these functions and parses the results.
Common request fields for all Lua scripts
The following request fields are supported
| Name | Type | Precense | Additional info |
|---|---|---|---|
| debug | bool | always | - |
| repeating | bool | maybe | - |
| user_found | bool | maybe | - |
| authenticated | bool | maybe | - |
| no_auth | bool | always | true, if the reuqest is used to retrieve user information |
| service | string | always | Nauthilus endpoint like "dovecot" or "nginx" |
| session | string | always | - |
| client_ip | string | always | - |
| client_port | string | always | - |
| client_host | string | maybe | - |
| client_net | string | maybe | Available in conjunction with brute-force-actions |
| client_id | string | maybe | - |
| user_agent | string | maybe | - |
| local_ip | string | always | - |
| local_port | string | always | - |
| username | string | always | - |
| account | string | maybe | Filter and post actions |
| unique_user_id | string | maybe | Used with OIDC subject |
| display_name | string | maybe | - |
| password | string | always | - |
| protocol | string | always | - |
| brute_force_bucket | string | maybe | Available in conjunction with brute-force-actions |
| feature | string | maybe | In actions, if a feature has triggered |
| status_message | string | always | Current status message returned to client, if auth request failed |
| ssl | string | maybe | HAproxy: %[ssl_fc] |
| ssl_session_id | string | maybe | HAproxy: %[ssl_fc_session_id,hex] |
| ssl_client_verify | string | maybe | HAproxy: %[ssl_c_verify] |
| ssl_client_dn | string | maybe | HAproxy: %{+Q}[ssl_c_s_dn] |
| ssl_client_cn | string | maybe | HAproxy: %{+Q}[ssl_c_s_dn(cn)] |
| ssl_issuer | string | maybe | HAproxy: %{+Q}[ssl_c_i_dn] |
| ssl_client_not_before | string | maybe | HAproxy: %{+Q}[ssl_c_notbefore] |
| ssl_client_not_after | string | maybe | HAproxy: %{+Q}[ssl_c_notafter] |
| ssl_subject_dn | string | maybe | HAproxy: %{+Q}[ssl_c_s_dn] |
| ssl_issuer_dn | string | maybe | HAproxy: %{+Q}[ssl_c_i_dn] |
| ssl_client_subject_dn | string | maybe | HAproxy: %{+Q}[ssl_c_s_dn] |
| ssl_client_issuer_dn | string | maybe | HAproxy: %{+Q}[ssl_c_i_dn] |
| ssl_protocol | string | maybe | HAproxy: %[ssl_fc_protocol] |
| ssl_cipher | string | maybe | HAproxy: %[ssl_fc_cipher] |
| ssl_serial | string | maybe | SSL certificate serial number |
| ssl_fingerprint | string | maybe | SSL certificate fingerprint |
| brute_force_counter | number | always | Current brute force attempt counter |
| account_field | string | maybe | The name of the field that contains the account |
| method | string | maybe | HTTP method (e.g., "GET", "POST") |
| oidc_cid | string | maybe | OIDC Client ID |
| log_format | string | always | Configured log format ("default" or "json") |
| log_level | string | always | Configured log level |
| logging | table | always | Table containing log_format and log_level |
| latency | number | always | Request processing latency |
| http_status | number | always | HTTP status code returned to the client |
| redis_prefix | string | always | Configured Redis key prefix |
TLS-related values may be retrieved from Nginx and as a fallback tried to be retrieved from HAproxy headers.
It is always a good idea to check the value of a request field, before using it.
Features
A Lua feature script must provide the following function:
---@param request table
---@return number, number, number
function nauthilus_call_feature(request)
return trigger, skip_flag, failure_info -- See details below
end
It must return three values: The trigger state, a flag that indicates, if other features shall be skipped and a third value which is an indicator for errors that occurred in the script itself.
Constants for the returned result
| Constant | Meaning | Value | Category |
|---|---|---|---|
| nauthilus_builtin.FEATURE_TRIGGER_NO | The feature has not been triggered | false | trigger |
| nauthilus_builtin.FEATURE_TRIGGER_YES | The feature has been triggered and the request must be rejected | true | trigger |
| nauthilus_builtin.FEATURES_ABORT_NO | Process other built-in features | false | skip_flag |
| nauthilus_builtin.FEATURES_ABORT_YES | After finishing the script, skip all other built-in features | true | skip_flag |
| nauthilus_builtin.FEATURE_RESULT_OK | The script finished without errors | 0 | failure_info |
| nauthilus_builtin.FEATURE_RESULT_FAIL | Something went wrong while executing the script | 1 | failure_info |
Request fields
Only common request fields are present.
Filters
A Lua filter script must provide the following function:
---@param request table
---@return number, number, number
function nauthilus_call_filter(request)
if request.authenticated then
-- do something
end
return filter_action, failure_info -- See details below
end
It must return three values: The trigger state, a flag that indicates, if other features shall be skipped and a third value which is an indicator for errors that occurred in the script itself.
Constants for the returned result
| Constant | Meaning | Value | Category |
|---|---|---|---|
| nauthilus_builtin.FILTER_ACCEPT | The request must be accepted | false | filter_action |
| nauthilus_builtin.FILTER_REJECT | The request has to be rejected | true | filter_action |
| nauthilus_builtin.FILTER_RESULT_OK | The script finished without errors | 0 | filter_info |
| nauthilus_builtin.FILTER_RESULT_FAIL | Something went wrong while executing the script | 1 | filter_info |
Request fields
Only common request fields are present.
Actions (including post)
A Lua action script must provide the following function:
---@param request table
---@return number
function nauthilus_call_action(request)
if request.no_auth then
-- Example post action: Store request information in database
end
return failure_info -- See details below
end
Actions must return the script status constant.
Constants for the returned result
| Constant | Meaning | Value | Category |
|---|---|---|---|
| nauthilus_builtin.ACTION_RESULT_OK | The script finished without errors | 0 | failure_info |
| nauthilus_builtin.ACTION_RESULT_FAIL | The script finished with errors | 1 | failure_info |
Request fields
Only common request fields are available.
Lua Backend
The Lua backend script must provide the following function:
---@param request table
---@return number, userdata
function nauthilus_backend_verify_password(request)
local backend_result_object = backend_result:new()
-- Do something with backend_result_object
return failure_info, backend_result_object -- See details below
end
For user account listing, the following function is required:
---@param request table
------@return number, table
function nauthilus_backend_list_accounts(request)
local accounts = {}
return failure_info, accounts -- See details below
end
If you plan on adding TOTP-keys for your users, you must provide the follwing function:
---@param request table
---@return number
function nauthilus_backend_add_totp(request)
return failure_info -- See details below
end
The backend must return the result status constant and a backend result object
Constants for the returned result
| Constant | Meaning | Value | Category |
|---|---|---|---|
| nauthilus_builtin.BACKEND_RESULT_OK | The script finished without errors | 0 | failure_info |
| nauthilus_builtin.BACKEND_RESULT_FAIL | The script finished with errors | 1 | failure_info |
Request fields
Function nauthilus_backend_verify_password request fields
Only common request fields are used.
Function nauthilus_backend_list_accounts request fields
Only "debug" and "session" from the common requests are available.
Function nauthilus_backend_add_totp request fields
Only "debug" and "session" from the common requests as well as "totp_secret" (string) are available.
UserData object backend_result
The nauthilus_backend_result object can be initialized in the Lua backend and in Lua filters. The following methods exist:
backend
| Name | Meaning |
|---|---|
| authenticated | Set or get the authentication status |
| user_found | Set or get the user found flag which indicated, if the backend found the user |
| account_field | Set or get the account field name, which must have been added to a list of result attributes |
| totp_secret_field | Set or get the TOTP secret field name, which must have been added to the result attributes |
| totp_recovery_field | Not yet implemented |
| unique_user_id_field | Set or get the unique user id field, which must have been added to the result attributes |
| display_name_field | Set or get the display name field, which must have been added to the result attributes |
| attributes | Set or get the result attributes as a Lua table |
filters
Filters only have an "attributes" method. While Lua backends do return a nauthlus_backend_result directly, filters can only apply it with a Lua function called "nauthilus_backend.apply_backend_result(backend_result_object)".
Attributes can not overwrite existing attributes!
Example usage for nauthilus_backend_result
local attributes = {}
attributes["account"] = "bob"
local b = nauthilus_backend_result.new()
b:attributes(attributes) -- Add the table
b:account_field("account") -- Attributes contain a key "account" for the account field
b:authenticated(true) -- User is authenticated
b:user_found(true) -- The user was found
Endpoints /api/v1/mail/dovecot, /api/v1/generic/user and /api/v1/generic/json
"attributes" represent a common result store for a backend query. All fields that have been set by *_field methods will be used for further internal processing, while all other attributes will be converted to HTTP-response-headers, which will be sent back to the client application that talked to Nauthilus. These headeres will be prefixed with X-Nauthilus-.
For the generic endpoints, "attributes" will bew returned in the JSON respone.
Additional notes
Nauthilus uses the gopher-lua-libs library in all Lua scripts. Please have a look at their documentation for all the modules that can directly be used in Nauthilus scripts: