Mercurial > prosody-modules

comparison mod_auth_external/README.wiki @ 1782:29f3d6b7ad16

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import wiki pages
author Kim Alvefur <zash@zash.se>
date Mon, 24 Aug 2015 16:43:56 +0200
parents
children
comparison
equal deleted inserted replaced
1781:12ac88940fe3 1782:29f3d6b7ad16
1 #summary Authentication via external script/process
2 #labels Stage-Alpha,Type-Auth
3
4 = Introduction =
5
6 Allow client authentication to be handled by an external script/process.
7
8 = Installation =
9
10 mod_auth_external depends on a Lua module called [http://www.tset.de/lpty/ lpty]. You can install it on many platforms using [http://luarocks.org/ LuaRocks], for example:
11
12 {{{
13 sudo luarocks install lpty
14 }}}
15
16 Note: Earlier versions of the module did not depend on lpty. While using the newer version is strongly recommended, you can find the [https://prosody-modules.googlecode.com/hg-history/50ee38e95e754bf1034d980364f93564028b2f34/mod_auth_external/mod_auth_external.lua older version here] if you need it (revision 50ee38e95e75 of the repository).
17
18 = Configuration =
19
20 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:
21
22 {{{
23 authentication = "external"
24 }}}
25
26 These options are specific to mod_auth_external:
27
28 ||external_auth_protocol||May be "generic" or "ejabberd" (the latter for compatibility with ejabberd external auth scripts. Default is "generic".||
29 ||external_auth_command||The command/script to execute.||
30
31 Two other options are also available, depending on whether the module is running in 'blocking' or 'non-blocking' mode:
32 ||external_auth_timeout||blocking||The number of seconds to wait for a response from the auth process. Default is 5.||
33 ||external_auth_processes||non-blocking||The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.||
34
35 == Blocking vs non-blocking ==
36
37 Non-blocking mode is automatically activated when:
38
39 * Running Prosody trunk ([http://prosody.im/nightly/ nightly] build 414+).
40 * [http://prosody.im/doc/libevent libevent] is enabled in the config, and LuaEvent is available.
41 * lpty (see installation above) is version 1.0.1 or later.
42
43 = Protocol =
44
45 Prosody executes the given command/script, and sends it queries.
46
47 Your auth script should simply read a line from standard input, and write the result to standard output.
48 It must do this in a loop, until there's nothing left to read. Prosody can keep sending more lines to the script,
49 with a command on each line.
50
51 Each command is one line, and the response is expected to be a single line containing "0" for failure or "1" for success.
52 Your script must respond with "0" for anything it doesn't understand.
53
54 There are three commands used at the moment:
55
56 == auth ==
57 Check if a user's password is valid.
58
59 Example: {{{auth:username:example.com:abc123}}}
60
61 Note: The password can contain colons. Make sure to handle that.
62
63 == isuser ==
64 Check if a user exists.
65
66 Example: {{{isuser:username:example.com}}}
67
68 == setpass ==
69 Set a new password for the user. Implementing this is optional.
70
71 Example: {{{setpass:username:example.com:abc123}}}
72
73 Note: The password can contain colons. Make sure to handle that.
74
75 == ejabberd compatibilty ==
76 ejabberd implements a similar protocol. The main difference is that Prosody's protocol is line-based, while ejabberd's is length-prefixed.
77
78 Add this to your config if you need to use an ejabberd auth script:
79 {{{
80 external_auth_protocol = "ejabberd"
81 }}}
82
83 = Compatibility =
84 ||0.8||Works||
85 ||0.9||Works||