Allow client authentication to be handled by an external script/process.


mod_auth_external depends on a Lua module called lpty. You can install it on many platforms using LuaRocks, for example:

sudo luarocks install lpty

Note: Earlier versions of the module did not depend on lpty. While using the newer version is strongly recommended, you can find the older version here if you need it (revision of the repository).


As with all auth modules, there is no need to add this to modules_enabled. Simply add in the global section, or for the relevant hosts:

authentication = "external"

These options are specific to mod_auth_external:

external_auth_protocol May be “generic” or “ejabberd” (the latter for compatibility with ejabberd external auth scripts. Default is “generic”.
external_auth_command The command/script to execute.

Two other options are also available, depending on whether the module is running in ‘blocking’ or ‘non-blocking’ mode:

external_auth_timeout blocking The number of seconds to wait for a response from the auth process. Default is 5.
external_auth_processes non-blocking The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.

Blocking vs non-blocking

Non-blocking mode is experimental and is disabled by default.

Enable at your own risk if you fulfil these conditions:

external_auth_blocking = false;


Prosody executes the given command/script, and sends it queries.

Your auth script should simply read a line from standard input, and write the result to standard output. It must do this in a loop, until there’s nothing left to read. Prosody can keep sending more lines to the script, with a command on each line.

Each command is one line, and the response is expected to be a single line containing “0” for failure or “1” for success. Your script must respond with “0” for anything it doesn’t understand.

There are three commands used at the moment:


Check if a user’s password is valid.


Note: The password can contain colons. Make sure to handle that.


Check if a user exists.



Set a new password for the user. Implementing this is optional.


Note: The password can contain colons. Make sure to handle that.

ejabberd compatibility

ejabberd implements a similar protocol. The main difference is that Prosody’s protocol is line-based, while ejabberd’s is length-prefixed.

Add this to your config if you need to use an ejabberd auth script:

    external_auth_protocol = "ejabberd"


0.8 Works
0.9 Works