prosody-modules
4d73a1a6ba68
mod_auth_external/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_auth_external/README.markdown @ 1803:4d73a1a6ba68

Convert all wiki pages to Markdown
author Kim Alvefur <zash@zash.se>
date Fri, 28 Aug 2015 18:03:58 +0200
parent 1782:mod_auth_external/README.wiki@29f3d6b7ad16
child 1820:8de50be756e5
comparison
equal deleted inserted replaced
1802:0ab737feada6 1803:4d73a1a6ba68
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 ----- -------