prosody-modules: mod_auth_external_insecure/README.markdown annotate

annotate mod_auth_external_insecure/README.markdown @ 5516:f25df3af02c1

mod_client_management: Include client software version number in listing Should you ever wish to revoke a client by version number, e.g. for security reasons affecting certain versions, then it would be good to at the very least see which version is used. Also includes the OAuth2 software ID, an optional unique identifier that should be the same for all installations of a particular software.

author	Kim Alvefur <zash@zash.se>
date	Sat, 03 Jun 2023 19:21:39 +0200
parents	8e58a1b78336
children

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 ----- -------

Mercurial > prosody-modules

annotate mod_auth_external_insecure/README.markdown @ 5516:f25df3af02c1