prosody-modules: mod_auth_http/README.markdown annotate

annotate mod_auth_http/README.markdown @ 4566:174c7a3c819b

mod_muc_bot: Add option to not send any messages to bots Useful for write-only bots that don't care about what's said in the chat.

author	Kim Alvefur <zash@zash.se>
date	Mon, 24 May 2021 16:18:29 +0200
parents	df1e0465ff81
children	1da63fe35ef3

rev	line source
4157 93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	1 ---
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 labels:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	3 - Stage-Alpha
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	4 summary: "Authenticate users against an external HTTP API"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	5 ...
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	6
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	7 # Overview
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	8
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	9 This authentication module allows Prosody to authenticate users against
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	10 an external HTTP service.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	11
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	12 # Configuration
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	13
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	14 ``` lua
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	15 VirtualHost "example.com"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	16 authentication = "http"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	17 http_auth_url = "http://example.com/auth"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	18 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	19
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	20 If the API requires Prosody to authenticate, you can provide static
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	21 credentials using HTTP Basic authentication, like so:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	22
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	23 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	24 http_auth_credentials = "prosody:secret-password"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	25 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	26
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	27 # Developers
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	28
4158 df1e0465ff81 mod_auth_http: Fix unfinished sentence in Matthew Wild <mwild1@gmail.com> parents: 4157 diff changeset	29 This section contains information for developers who wish to implement a
df1e0465ff81 mod_auth_http: Fix unfinished sentence in Matthew Wild <mwild1@gmail.com> parents: 4157 diff changeset	30 HTTP service that Prosody can use for authentication.
4157 93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	31
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	32 ## Protocol
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	33
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	34 Prosody will make a HTTP request to the configured API URL with an
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	35 appended `/METHOD` where `METHOD` is one of the methods described below.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	36
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	37 GET methods must expect a series of URL-encoded query parameters, while
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	38 POST requests will receive an URL-encoded form (i.e.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	39 `application/x-www-form-urlencoded`).
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	40
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	41 ## Parameters
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	42
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	43 user
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	44 : The username, e.g. `stephanie` for the JID `stephanie@example.com`.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	45
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	46 server
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	47 : The host part of the user's JID, e.g. `example.com` for the JID
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	48 `stephanie@example.com`.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	49
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	50 pass
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	51 : For methods that verify or set a user's password, the password will
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	52 be supplied in this parameter, otherwise it is not set.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	53
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	54 ## Methods
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	55
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	56 The only mandatory methods that the service must implement are `check_password`
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	57 and `user_exists`. Unsupported methods should return a HTTP status code
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	58 of `501 Not Implemented`, but other error codes will also be handled by
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	59 Prosody.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	60
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	61 ### register
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	62
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	63 HTTP method:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	64 : POST
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	65
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	66 Success codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	67 : 201
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	68
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	69 Error codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	70 : 409 (user exists)
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	71
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	72 ### check_password
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	73
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	74 HTTP method:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	75 : GET
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	76
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	77 Success codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	78 : 200
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	79
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	80 Response:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 : A text string of `true` if the user exists, or `false` otherwise.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	82
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	83 ### user_exists
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	84
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	85 HTTP method:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	86 : GET
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	87
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	88 Success codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	89 : 200
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	90
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	91 Response:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	92 : A text string of `true` if the user exists, or `false` otherwise.
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	93
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	94 ### set_password
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	95
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	96 HTTP method:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	97 : POST
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	98
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	99 Success codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	100 : 200, 201, or 204
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	101
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	102 ### remove_user
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	103
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	104 HTTP method:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	105 : POST
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	106
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	107 Success codes:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	108 : 200, 201 or 204
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	109
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	110 ## Examples
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	111
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	112 With the following configuration:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	113
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	114 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	115 authentication = "http"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	116 http_auth_url = "https://auth.example.net/api"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	117
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	118 If a user connects and tries to log in to Prosody as "romeo@example.net"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	119 with the password "iheartjuliet", Prosody would make the following HTTP
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	120 request:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	121
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	122 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	123 https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	124 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	125
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	126 # Compatibility
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	127
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	128 Requires Prosody 0.11.0 or later.

Mercurial > prosody-modules

annotate mod_auth_http/README.markdown @ 4566:174c7a3c819b