author | Kim Alvefur <zash@zash.se> |
Sun, 13 Sep 2015 15:45:40 +0200 | |
changeset 1848 | 04e168063fc7 |
parent 1824 | 8de50be756e5 |
child 2148 | ead81e222fde |
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 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
25 |
here](https://prosody-modules.googlecode.com/hg-history/50ee38e95e754bf1034d980364f93564028b2f34/mod_auth_external/mod_auth_external.lua) |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
26 |
if you need it (revision 50ee38e95e75 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 |
|
55 |
Non-blocking mode is automatically activated when: |
|
56 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
57 |
- Running Prosody trunk ([nightly](http://prosody.im/nightly/) build |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
58 |
414+). |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
59 |
- [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
|
60 |
and LuaEvent is available. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
61 |
- lpty (see installation above) is version 1.0.1 or later. |
1786 | 62 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
63 |
Protocol |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
64 |
======== |
1786 | 65 |
|
66 |
Prosody executes the given command/script, and sends it queries. |
|
67 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
68 |
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
|
69 |
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
|
70 |
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
|
71 |
script, with a command on each line. |
1786 | 72 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
73 |
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
|
74 |
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
|
75 |
respond with "0" for anything it doesn't understand. |
1786 | 76 |
|
77 |
There are three commands used at the moment: |
|
78 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
79 |
auth |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
80 |
---- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
81 |
|
1786 | 82 |
Check if a user's password is valid. |
83 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
84 |
Example: `auth:username:example.com:abc123` |
1786 | 85 |
|
86 |
Note: The password can contain colons. Make sure to handle that. |
|
87 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
88 |
isuser |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
89 |
------ |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
90 |
|
1786 | 91 |
Check if a user exists. |
92 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
93 |
Example: `isuser:username:example.com` |
1786 | 94 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
95 |
setpass |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
96 |
------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
97 |
|
1786 | 98 |
Set a new password for the user. Implementing this is optional. |
99 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
100 |
Example: `setpass:username:example.com:abc123` |
1786 | 101 |
|
102 |
Note: The password can contain colons. Make sure to handle that. |
|
103 |
||
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
104 |
ejabberd compatibilty |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
105 |
--------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
106 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
107 |
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
|
108 |
Prosody's protocol is line-based, while ejabberd's is length-prefixed. |
1786 | 109 |
|
110 |
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
|
111 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
112 |
external_auth_protocol = "ejabberd" |
1786 | 113 |
|
1807
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
114 |
Compatibility |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
115 |
============= |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
116 |
|
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 |
0.8 Works |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
119 |
0.9 Works |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1786
diff
changeset
|
120 |
----- ------- |