Mercurial > prosody-modules

comparison mod_auth_http/README.markdown @ 4157:93b12bfd7aa8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_auth_http: Yet another module to authenticate against a HTTP service
author Matthew Wild <mwild1@gmail.com>
date Wed, 30 Sep 2020 13:20:11 +0100
parents
children df1e0465ff81
comparison
equal deleted inserted replaced
4156:b79904446d9e 4157:93b12bfd7aa8
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
30
31 ## Protocol
32
33 Prosody will make a HTTP request to the configured API URL with an
34 appended `/METHOD` where `METHOD` is one of the methods described below.
35
36 GET methods must expect a series of URL-encoded query parameters, while
37 POST requests will receive an URL-encoded form (i.e.
38 `application/x-www-form-urlencoded`).
39
40 ## Parameters
41
42 user
43 : The username, e.g. `stephanie` for the JID `stephanie@example.com`.
44
45 server
46 : The host part of the user's JID, e.g. `example.com` for the JID
47 `stephanie@example.com`.
48
49 pass
50 : For methods that verify or set a user's password, the password will
51 be supplied in this parameter, otherwise it is not set.
52
53 ## Methods
54
55 The only mandatory methods that the service must implement are `check_password`
56 and `user_exists`. Unsupported methods should return a HTTP status code
57 of `501 Not Implemented`, but other error codes will also be handled by
58 Prosody.
59
60 ### register
61
62 **HTTP method:**
63 : POST
64
65 **Success codes:**
66 : 201
67
68 **Error codes:**
69 : 409 (user exists)
70
71 ### check_password
72
73 **HTTP method:**
74 : GET
75
76 **Success codes:**
77 : 200
78
79 **Response:**
80 : A text string of `true` if the user exists, or `false` otherwise.
81
82 ### user_exists
83
84 **HTTP method:**
85 : GET
86
87 **Success codes:**
88 : 200
89
90 **Response:**
91 : A text string of `true` if the user exists, or `false` otherwise.
92
93 ### set_password
94
95 **HTTP method:**
96 : POST
97
98 **Success codes:**
99 : 200, 201, or 204
100
101 ### remove_user
102
103 **HTTP method:**
104 : POST
105
106 **Success codes:**
107 : 200, 201 or 204
108
109 ## Examples
110
111 With the following configuration:
112
113 ```
114 authentication = "http"
115 http_auth_url = "https://auth.example.net/api"
116
117 If a user connects and tries to log in to Prosody as "romeo@example.net"
118 with the password "iheartjuliet", Prosody would make the following HTTP
119 request:
120
121 ```
122 https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet
123 ```
124
125 # Compatibility
126
127 Requires Prosody 0.11.0 or later.