Mercurial > prosody-modules

comparison mod_auth_http/README.md @ 5975:fe081789f7b5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parents mod_auth_http/README.markdown@1da63fe35ef3
children 889d24be0a49
comparison
equal deleted inserted replaced
5974:5a65a632d5b9 5975:fe081789f7b5
1 ---
2 labels:
3 - Stage-Alpha
4 summary: "Authenticate users against an external HTTP API"
5 ...
6
7 # Overview
8
9 This authentication module allows Prosody to authenticate users against
10 an external HTTP service.
11
12 # Configuration
13
14 ``` lua
15 VirtualHost "example.com"
16 authentication = "http"
17 http_auth_url = "http://example.com/auth"
18 ```
19
20 If the API requires Prosody to authenticate, you can provide static
21 credentials using HTTP Basic authentication, like so:
22
23 ```
24 http_auth_credentials = "prosody:secret-password"
25 ```
26
27 # Developers
28
29 This section contains information for developers who wish to implement a
30 HTTP service that Prosody can use for authentication.
31
32 ## Protocol
33
34 Prosody will make a HTTP request to the configured API URL with an
35 appended `/METHOD` where `METHOD` is one of the methods described below.
36
37 GET methods must expect a series of URL-encoded query parameters, while
38 POST requests will receive an URL-encoded form (i.e.
39 `application/x-www-form-urlencoded`).
40
41 ## Parameters
42
43 user
44 : The username, e.g. `stephanie` for the JID `stephanie@example.com`.
45
46 server
47 : The host part of the user's JID, e.g. `example.com` for the JID
48 `stephanie@example.com`.
49
50 pass
51 : For methods that verify or set a user's password, the password will
52 be supplied in this parameter, otherwise it is not set.
53
54 ## Methods
55
56 The only mandatory methods that the service must implement are `check_password`
57 and `user_exists`. Unsupported methods should return a HTTP status code
58 of `501 Not Implemented`, but other error codes will also be handled by
59 Prosody.
60
61 Method HTTP method Success codes Error codes Response
62 -------- ---- --- ----------------- -----------------------------------------------------------------
63 register POST 201 409 (user exists)
64 check\_password GET 200 A text string of `true` if the user exists, or `false` otherwise.
65 user\_exists GET 200 A text string of `true` if the user exists, or `false` otherwise.
66 set\_password POST 200, 201 or 204
67 remove\_user POST 200, 201 or 204
68
69 ## Examples
70
71 With the following configuration:
72
73 ```
74 authentication = "http"
75 http_auth_url = "https://auth.example.net/api"
76
77 If a user connects and tries to log in to Prosody as "romeo@example.net"
78 with the password "iheartjuliet", Prosody would make the following HTTP
79 request:
80
81 ```
82 https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet
83 ```
84
85 # Compatibility
86
87 Requires Prosody 0.11.0 or later.