1 ---

     2 labels:

     3 - 'Stage-Alpha'

     4 - 'Type-Auth'

     5 summary: 'Authentication via external script/process'

     6 ...

     7 

     8 Introduction

     9 ============

    10 

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

    12 

    13 Installation

    14 ============

    15 

    16 mod\_auth\_external depends on a Lua module called

    17 [lpty](http://www.tset.de/lpty/). You can install it on many platforms

    18 using [LuaRocks](http://luarocks.org/), for example:

    19 

    20        sudo luarocks install lpty

    21 

    22 Note: Earlier versions of the module did not depend on lpty. While using

    23 the newer version is strongly recommended, you can find the [older

    24 version

    25 here](https://prosody-modules.googlecode.com/hg-history/50ee38e95e754bf1034d980364f93564028b2f34/mod_auth_external/mod_auth_external.lua)

    26 if you need it (revision 50ee38e95e75 of the repository).

    27 

    28 Configuration

    29 =============

    30 

    31 As with all auth modules, there is no need to add this to

    32 modules\_enabled. Simply add in the global section, or for the relevant

    33 hosts:

    34 

    35         authentication = "external"

    36 

    37 These options are specific to mod\_auth\_external:

    38 

    39   -------------------------- -------------------------------------------------------------------------------------------------------------------------

    40   external\_auth\_protocol   May be "generic" or "ejabberd" (the latter for compatibility with ejabberd external auth scripts. Default is "generic".

    41   external\_auth\_command    The command/script to execute.

    42   -------------------------- -------------------------------------------------------------------------------------------------------------------------

    43 

    44 Two other options are also available, depending on whether the module is

    45 running in 'blocking' or 'non-blocking' mode:

    46 

    47   --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------

    48   external\_auth\_timeout     blocking       The number of seconds to wait for a response from the auth process. Default is 5.

    49   external\_auth\_processes   non-blocking   The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.

    50   --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------

    51 

    52 Blocking vs non-blocking

    53 ------------------------

    54 

    55 Non-blocking mode is automatically activated when:

    56 

    57 -   Running Prosody trunk ([nightly](http://prosody.im/nightly/) build

    58     414+).

    59 -   [libevent](http://prosody.im/doc/libevent) is enabled in the config,

    60     and LuaEvent is available.

    61 -   lpty (see installation above) is version 1.0.1 or later.

    62 

    63 Protocol

    64 ========

    65 

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

    67 

    68 Your auth script should simply read a line from standard input, and

    69 write the result to standard output. It must do this in a loop, until

    70 there's nothing left to read. Prosody can keep sending more lines to the

    71 script, with a command on each line.

    72 

    73 Each command is one line, and the response is expected to be a single

    74 line containing "0" for failure or "1" for success. Your script must

    75 respond with "0" for anything it doesn't understand.

    76 

    77 There are three commands used at the moment:

    78 

    79 auth

    80 ----

    81 

    82 Check if a user's password is valid.

    83 

    84 Example: `auth:username:example.com:abc123`

    85 

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

    87 

    88 isuser

    89 ------

    90 

    91 Check if a user exists.

    92 

    93 Example: `isuser:username:example.com`

    94 

    95 setpass

    96 -------

    97 

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

    99 

   100 Example: `setpass:username:example.com:abc123`

   101 

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

   103 

   104 ejabberd compatibilty

   105 ---------------------

   106 

   107 ejabberd implements a similar protocol. The main difference is that

   108 Prosody's protocol is line-based, while ejabberd's is length-prefixed.

   109 

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

   111 

   112         external_auth_protocol = "ejabberd"

   113 

   114 Compatibility

   115 =============

   116 

   117   ----- -------

   118   0.8   Works

   119   0.9   Works

   120   ----- -------