Mercurial > prosody-modules

annotate mod_auth_http/README.markdown @ 4303:d261233f7ced

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve UX by providing defaults users expect
author Seve Ferrer <seve@delape.net>
date Fri, 18 Dec 2020 15:28:12 +0100
parents df1e0465ff81
children 1da63fe35ef3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.