Mercurial > prosody-modules
annotate mod_auth_http/README.markdown @ 5193:2bb29ece216b
mod_http_oauth2: Implement stateless dynamic client registration
Replaces previous explicit registration that required either the
additional module mod_adhoc_oauth2_client or manually editing the
database. That method was enough to have something to test with, but
would not probably not scale easily.
Dynamic client registration allows creating clients on the fly, which
may be even easier in theory.
In order to not allow basically unauthenticated writes to the database,
we implement a stateless model here.
per_host_key := HMAC(config -> oauth2_registration_key, hostname)
client_id := JWT { client metadata } signed with per_host_key
client_secret := HMAC(per_host_key, client_id)
This should ensure everything we need to know is part of the client_id,
allowing redirects etc to be validated, and the client_secret can be
validated with only the client_id and the per_host_key.
A nonce injected into the client_id JWT should ensure nobody can submit
the same client metadata and retrieve the same client_secret
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 03 Mar 2023 21:14:19 +0100 |
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. |