mod_auth_external/README.markdown

   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://hg.prosody.im/prosody-modules/raw-file/50ee38e95e75/mod_auth_external/mod_auth_external.lua)
  26 if you need it (revision 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 experimental and is disabled by default.
  56
  57 Enable at your own risk if you fulfil these conditions:
  58
  59 -   Running Prosody trunk ([nightly](http://prosody.im/nightly/) build
  60     414+) or Prosody 0.11.x.
  61 -   [libevent](http://prosody.im/doc/libevent) is enabled in the config,
  62     and LuaEvent is available.
  63 -   lpty (see installation above) is version 1.0.1 or later.
  64
  65 ```lua
  66 external_auth_blocking = false;
  67 ```
  68
  69 Protocol
  70 ========
  71
  72 Prosody executes the given command/script, and sends it queries.
  73
  74 Your auth script should simply read a line from standard input, and
  75 write the result to standard output. It must do this in a loop, until
  76 there's nothing left to read. Prosody can keep sending more lines to the
  77 script, with a command on each line.
  78
  79 Each command is one line, and the response is expected to be a single
  80 line containing "0" for failure or "1" for success. Your script must
  81 respond with "0" for anything it doesn't understand.
  82
  83 There are three commands used at the moment:
  84
  85 auth
  86 ----
  87
  88 Check if a user's password is valid.
  89
  90 Example: `auth:username:example.com:abc123`
  91
  92 Note: The password can contain colons. Make sure to handle that.
  93
  94 isuser
  95 ------
  96
  97 Check if a user exists.
  98
  99 Example: `isuser:username:example.com`
 100
 101 setpass
 102 -------
 103
 104 Set a new password for the user. Implementing this is optional.
 105
 106 Example: `setpass:username:example.com:abc123`
 107
 108 Note: The password can contain colons. Make sure to handle that.
 109
 110 ejabberd compatibility
 111 ---------------------
 112
 113 ejabberd implements a similar protocol. The main difference is that
 114 Prosody's protocol is line-based, while ejabberd's is length-prefixed.
 115
 116 Add this to your config if you need to use an ejabberd auth script:
 117
 118         external_auth_protocol = "ejabberd"
 119
 120 Compatibility
 121 =============
 122
 123   ----- -------
 124   0.8   Works
 125   0.9   Works
 126   ----- -------