author | Kim Alvefur <zash@zash.se> |
Sat, 25 Jan 2020 01:31:49 +0100 | |
changeset 3861 | 8752e5b5dd08 |
parent 3394 | 3287dd234f3f |
permissions | -rw-r--r-- |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
1 |
--- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
2 |
labels: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
3 |
- 'Stage-Alpha' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
4 |
- 'Type-Auth' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
5 |
summary: 'Authentication via external script/process' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
6 |
... |
1786 | 7 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
8 |
Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
9 |
============ |
1786 | 10 |
|
11 |
Allow client authentication to be handled by an external script/process. |
|
12 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
13 |
Installation |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
14 |
============ |
1786 | 15 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
16 |
mod\_auth\_external depends on a Lua module called |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
17 |
[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:
1786
diff
changeset
|
18 |
using [LuaRocks](http://luarocks.org/), for example: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
19 |
|
1824
8de50be756e5
Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents:
1807
diff
changeset
|
20 |
sudo luarocks install lpty |
1786 | 21 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
22 |
Note: Earlier versions of the module did not depend on lpty. While using |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
23 |
the newer version is strongly recommended, you can find the [older |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
24 |
version |
2148
ead81e222fde
mod_auth_external/README: Update link from google code to hg.prosody.im
Kim Alvefur <zash@zash.se>
parents:
1824
diff
changeset
|
25 |
here](https://hg.prosody.im/prosody-modules/raw-file/50ee38e95e75/mod_auth_external/mod_auth_external.lua) |
ead81e222fde
mod_auth_external/README: Update link from google code to hg.prosody.im
Kim Alvefur <zash@zash.se>
parents:
1824
diff
changeset
|
26 |
if you need it (revision of the repository). |
1786 | 27 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
28 |
Configuration |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
29 |
============= |
1786 | 30 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
33 |
hosts: |
1786 | 34 |
|
1824
8de50be756e5
Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents:
1807
diff
changeset
|
35 |
authentication = "external" |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
36 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
37 |
These options are specific to mod\_auth\_external: |
1786 | 38 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
39 |
-------------------------- ------------------------------------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
41 |
external\_auth\_command The command/script to execute. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
42 |
-------------------------- ------------------------------------------------------------------------------------------------------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
43 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
45 |
running in 'blocking' or 'non-blocking' mode: |
1786 | 46 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
47 |
--------------------------- -------------- ------------------------------------------------------------------------------------------------------------------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
50 |
--------------------------- -------------- ------------------------------------------------------------------------------------------------------------------ |
1786 | 51 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
52 |
Blocking vs non-blocking |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
53 |
------------------------ |
1786 | 54 |
|
3393
788200f5f481
mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents:
2880
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:
2880
diff
changeset
|
56 |
|
788200f5f481
mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents:
2880
diff
changeset
|
57 |
Enable at your own risk if you fulfil these conditions: |
1786 | 58 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
59 |
- Running Prosody trunk ([nightly](http://prosody.im/nightly/) build |
3394
3287dd234f3f
mod_auth_external/README: Update mentioning 0.11.x
Kim Alvefur <zash@zash.se>
parents:
3393
diff
changeset
|
60 |
414+) or Prosody 0.11.x. |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
62 |
and LuaEvent is available. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
63 |
- lpty (see installation above) is version 1.0.1 or later. |
1786 | 64 |
|
3393
788200f5f481
mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents:
2880
diff
changeset
|
65 |
```lua |
788200f5f481
mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents:
2880
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:
2880
diff
changeset
|
67 |
``` |
788200f5f481
mod_auth_external/README: Update to reflect non-blocking by default
Kim Alvefur <zash@zash.se>
parents:
2880
diff
changeset
|
68 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
69 |
Protocol |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
70 |
======== |
1786 | 71 |
|
72 |
Prosody executes the given command/script, and sends it queries. |
|
73 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
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:
1786
diff
changeset
|
77 |
script, with a command on each line. |
1786 | 78 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
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:
1786
diff
changeset
|
81 |
respond with "0" for anything it doesn't understand. |
1786 | 82 |
|
83 |
There are three commands used at the moment: |
|
84 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
85 |
auth |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
86 |
---- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
87 |
|
1786 | 88 |
Check if a user's password is valid. |
89 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
90 |
Example: `auth:username:example.com:abc123` |
1786 | 91 |
|
92 |
Note: The password can contain colons. Make sure to handle that. |
|
93 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
94 |
isuser |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
95 |
------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
96 |
|
1786 | 97 |
Check if a user exists. |
98 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
99 |
Example: `isuser:username:example.com` |
1786 | 100 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
101 |
setpass |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
102 |
------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
103 |
|
1786 | 104 |
Set a new password for the user. Implementing this is optional. |
105 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
106 |
Example: `setpass:username:example.com:abc123` |
1786 | 107 |
|
108 |
Note: The password can contain colons. Make sure to handle that. |
|
109 |
||
2880 | 110 |
ejabberd compatibility |
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
111 |
--------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
112 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
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:
1786
diff
changeset
|
114 |
Prosody's protocol is line-based, while ejabberd's is length-prefixed. |
1786 | 115 |
|
116 |
Add this to your config if you need to use an ejabberd auth script: |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
117 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
118 |
external_auth_protocol = "ejabberd" |
1786 | 119 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
120 |
Compatibility |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
121 |
============= |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
122 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
123 |
----- ------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
124 |
0.8 Works |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
125 |
0.9 Works |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
126 |
----- ------- |