prosody-modules: mod_auth_http/README.markdown annotate

annotate mod_auth_http/README.markdown @ 5424:b45d9a81b3da

mod_http_oauth2: Revert role selector, going to try something else Back out f2c7bb3af600 Allowing only a single role to be encoded into the grant takes away the possibility of having multiple roles in the grant, one of which is selected when issuing an access token. It also takes away the ability to have zero roles granted, which could be useful e.g. when you only need OIDC scopes.

author	Kim Alvefur <zash@zash.se>
date	Sun, 07 May 2023 19:40:57 +0200
parents	1da63fe35ef3
children

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
4594 1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	61 Method HTTP method Success codes Error codes Response
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	62 -------- ---- --- ----------------- -----------------------------------------------------------------
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	63 register POST 201 409 (user exists)
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	64 check\_password GET 200 A text string of `true` if the user exists, or `false` otherwise.
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	65 user\_exists GET 200 A text string of `true` if the user exists, or `false` otherwise.
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	66 set\_password POST 200, 201 or 204
1da63fe35ef3 mod_auth_http: Format README better Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 4158 diff changeset	67 remove\_user POST 200, 201 or 204
4157 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 ## Examples
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	70
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	71 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	72
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 authentication = "http"
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	75 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	76
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	77 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	78 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	79 request:
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	80
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 ```
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	82 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	83 ```
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 # Compatibility
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	86
93b12bfd7aa8 mod_auth_http: Yet another module to authenticate against a HTTP service Matthew Wild <mwild1@gmail.com> parents: diff changeset	87 Requires Prosody 0.11.0 or later.

Mercurial > prosody-modules

annotate mod_auth_http/README.markdown @ 5424:b45d9a81b3da