Mercurial > prosody-modules

annotate mod_auth_external_insecure/README.markdown @ 5739:7e6bf0a5aef2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: Add a basic grafterm dashboard For those of us who would rather have less JavaScript
author Kim Alvefur <zash@zash.se>
date Mon, 27 Nov 2023 17:16:15 +0100
parents 8e58a1b78336
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
3 - 'Stage-Deprecated'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 - 'Type-Auth'
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
5 summary: 'Authentication via external script/process (DEPRECATED)'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
6 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
8 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
9 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 Allow client authentication to be handled by an external script/process.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
4558
8e58a1b78336 mod_auth_external_insecure: Wrap warning in scary div
Kim Alvefur <zash@zash.se>
parents: 3884
diff changeset
13 :::{.alert .alert-warning}
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
14 **Warning:** This module is not currently maintained, and may be buggy and insecure in
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
15 certain configurations/environments. It is **not** recommended for production use. Please
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
16 use one of the [many other authentication modules](/type_auth).
4558
8e58a1b78336 mod_auth_external_insecure: Wrap warning in scary div
Kim Alvefur <zash@zash.se>
parents: 3884
diff changeset
17 :::
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
18
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
19 Installation
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
22 mod\_auth\_external\_insecure depends on a Lua module called
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 [lpty](http://www.tset.de/lpty/). You can install it on many platforms
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 using [LuaRocks](http://luarocks.org/), for example:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
25
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
26 sudo luarocks install lpty
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
28 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
29 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
31 As with all auth modules, there is no need to add this to
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
32 modules\_enabled. Simply add in the global section, or for the relevant
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33 hosts:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
35 authentication = "external_insecure"
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
36
3884
f84ede3e9e3b mod_auth_external->mod_auth_external_insecure: Unmaintained and almost certainly insecure, discourage its use
Matthew Wild <mwild1@gmail.com>
parents: 3391
diff changeset
37 These options are specific to mod\_auth\_external\_insecure:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
39 -------------------------- -------------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
40 external\_auth\_protocol May be "generic" or "ejabberd" (the latter for compatibility with ejabberd external auth scripts. Default is "generic".
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
41 external\_auth\_command The command/script to execute.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
42 -------------------------- -------------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
43
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
44 Two other options are also available, depending on whether the module is
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
45 running in 'blocking' or 'non-blocking' mode:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
47 --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
48 external\_auth\_timeout blocking The number of seconds to wait for a response from the auth process. Default is 5.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
49 external\_auth\_processes non-blocking The number of concurrent processes to spawn. Default is 1, increase to handle high connection rates efficiently.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
50 --------------------------- -------------- ------------------------------------------------------------------------------------------------------------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
52 Blocking vs non-blocking
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
53 ------------------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
3390
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
55 Non-blocking mode is experimental and is disabled by default.
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
56
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
57 Enable at your own risk if you fulfil these conditions:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
59 - Running Prosody trunk ([nightly](http://prosody.im/nightly/) build
3391
3287dd234f3f mod_auth_external/README: Update mentioning 0.11.x
Kim Alvefur <zash@zash.se>
parents: 3390
diff changeset
60 414+) or Prosody 0.11.x.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
61 - [libevent](http://prosody.im/doc/libevent) is enabled in the config,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
62 and LuaEvent is available.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
63 - lpty (see installation above) is version 1.0.1 or later.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64
3390
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
65 ```lua
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
66 external_auth_blocking = false;
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
67 ```
788200f5f481 mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents: 2876
diff changeset
68
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
69 Protocol
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
70 ========
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 Prosody executes the given command/script, and sends it queries.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
74 Your auth script should simply read a line from standard input, and
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
75 write the result to standard output. It must do this in a loop, until
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
76 there's nothing left to read. Prosody can keep sending more lines to the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
77 script, with a command on each line.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
79 Each command is one line, and the response is expected to be a single
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
80 line containing "0" for failure or "1" for success. Your script must
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
81 respond with "0" for anything it doesn't understand.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 There are three commands used at the moment:
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
85 auth
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
86 ----
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
87
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88 Check if a user's password is valid.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
90 Example: `auth:username:example.com:abc123`
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92 Note: The password can contain colons. Make sure to handle that.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
94 isuser
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
95 ------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
96
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
97 Check if a user exists.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
99 Example: `isuser:username:example.com`
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
100
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
101 setpass
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
102 -------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
103
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
104 Set a new password for the user. Implementing this is optional.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
105
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
106 Example: `setpass:username:example.com:abc123`
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
107
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
108 Note: The password can contain colons. Make sure to handle that.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
109
2876
ea6b5321db50 README files: Fix typos
Kim Alvefur <zash@zash.se>
parents: 2144
diff changeset
110 ejabberd compatibility
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
111 ---------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
112
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
113 ejabberd implements a similar protocol. The main difference is that
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
114 Prosody's protocol is line-based, while ejabberd's is length-prefixed.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
115
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
116 Add this to your config if you need to use an ejabberd auth script:
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
117
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
118 external_auth_protocol = "ejabberd"
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
120 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
121 =============
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
122
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
123 ----- -------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
124 0.8 Works
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
125 0.9 Works
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
126 ----- -------