Mercurial > prosody-modules

comparison mod_auth_external_insecure/README.markdown @ 3884:f84ede3e9e3b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
author Matthew Wild <mwild1@gmail.com>
date Thu, 06 Feb 2020 21:03:17 +0000
parents mod_auth_external/README.markdown@3287dd234f3f
children 8e58a1b78336
comparison
equal deleted inserted replaced
3883:571249f69577 3884:f84ede3e9e3b
1 ---
2 labels:
3 - 'Stage-Deprecated'
4 - 'Type-Auth'
5 summary: 'Authentication via external script/process (DEPRECATED)'
6 ...
7
8 Introduction
9 ============
10
11 Allow client authentication to be handled by an external script/process.
12
13 **Warning:** This module is not currently maintained, and may be buggy and insecure in
14 certain configurations/environments. It is **not** recommended for production use. Please
15 use one of the [many other authentication modules](/type_auth).
16
17 Installation
18 ============
19
20 mod\_auth\_external\_insecure depends on a Lua module called
21 [lpty](http://www.tset.de/lpty/). You can install it on many platforms
22 using [LuaRocks](http://luarocks.org/), for example:
23
24 sudo luarocks install lpty
25
26 Configuration
27 =============
28
29 As with all auth modules, there is no need to add this to
30 modules\_enabled. Simply add in the global section, or for the relevant
31 hosts:
32
33 authentication = "external_insecure"
34
35 These options are specific to mod\_auth\_external\_insecure:
36
37 -------------------------- -------------------------------------------------------------------------------------------------------------------------
38 external\_auth\_protocol May be "generic" or "ejabberd" (the latter for compatibility with ejabberd external auth scripts. Default is "generic".
39 external\_auth\_command The command/script to execute.
40 -------------------------- -------------------------------------------------------------------------------------------------------------------------
41
42 Two other options are also available, depending on whether the module is
43 running in 'blocking' or 'non-blocking' mode:
44
45 --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------
46 external\_auth\_timeout blocking The number of seconds to wait for a response from the auth process. Default is 5.
47 external\_auth\_processes non-blocking The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.
48 --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------
49
50 Blocking vs non-blocking
51 ------------------------
52
53 Non-blocking mode is experimental and is disabled by default.
54
55 Enable at your own risk if you fulfil these conditions:
56
57 - Running Prosody trunk ([nightly](http://prosody.im/nightly/) build
58 414+) or Prosody 0.11.x.
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 ```lua
64 external_auth_blocking = false;
65 ```
66
67 Protocol
68 ========
69
70 Prosody executes the given command/script, and sends it queries.
71
72 Your auth script should simply read a line from standard input, and
73 write the result to standard output. It must do this in a loop, until
74 there's nothing left to read. Prosody can keep sending more lines to the
75 script, with a command on each line.
76
77 Each command is one line, and the response is expected to be a single
78 line containing "0" for failure or "1" for success. Your script must
79 respond with "0" for anything it doesn't understand.
80
81 There are three commands used at the moment:
82
83 auth
84 ----
85
86 Check if a user's password is valid.
87
88 Example: `auth:username:example.com:abc123`
89
90 Note: The password can contain colons. Make sure to handle that.
91
92 isuser
93 ------
94
95 Check if a user exists.
96
97 Example: `isuser:username:example.com`
98
99 setpass
100 -------
101
102 Set a new password for the user. Implementing this is optional.
103
104 Example: `setpass:username:example.com:abc123`
105
106 Note: The password can contain colons. Make sure to handle that.
107
108 ejabberd compatibility
109 ---------------------
110
111 ejabberd implements a similar protocol. The main difference is that
112 Prosody's protocol is line-based, while ejabberd's is length-prefixed.
113
114 Add this to your config if you need to use an ejabberd auth script:
115
116 external_auth_protocol = "ejabberd"
117
118 Compatibility
119 =============
120
121 ----- -------
122 0.8 Works
123 0.9 Works
124 ----- -------