prosody-modules: mod_auth_http/README.markdown annotate

annotate mod_auth_http/README.markdown @ 4537:53ee391ca689

mod_smacks: Fix traceback due to session being destroyed in send() Sending something can cause the OS to notice that the connection is dead and then the connection can be dead at this point. More likely if opportunistic_writes is enabled.

author	Kim Alvefur <zash@zash.se>
date	Thu, 01 Apr 2021 11:35:26 +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 @ 4537:53ee391ca689