Mercurial > prosody-modules

annotate mod_auth_http/README.markdown @ 4203:c4002aae4ad3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_s2s_keepalive: Use timestamp as iq @id RFC 6120 implies that the id attribute must be unique within a stream. This should fix problems with remote servers that enforce uniqueness and don't answer duplicated ids. If it doesn't do that, then at least you can get a guesstimate at round-trip time from the difference between the result iq stanza and the timestamp it was logged without having to go look for when it was sent, or needing to keep state.
author Kim Alvefur <zash@zash.se>
date Wed, 14 Oct 2020 18:02:10 +0200
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.