Mercurial > prosody-modules

annotate mod_http_roster_admin/README.markdown @ 5401:c8d04ac200fc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Reject loopback URIs as client_uri This really should be a proper website with info, https://localhost is not good enough. Ideally we'd validate that it's got proper DNS and is actually reachable, but triggering HTTP or even DNS lookups seems like it would carry abuse potential that would best to avoid.
author Kim Alvefur <zash@zash.se>
date Tue, 02 May 2023 16:20:55 +0200
parents af1b3cef52e1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2311
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
1 ---
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
2 labels:
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
3 - 'Stage-Beta'
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
4 summary: Delegate roster management to an external service
73967121cf5e Add labels
JC Brand <jcbrand@minddistrict.com>
parents: 2310
diff changeset
5 ...
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
6
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
7 *NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.*
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
8
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
9 Normally the XMPP server will store and maintain the users' contact
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
10 rosters. This module lets you delegate roster management to an external
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
11 service.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
12
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
13 Prosody will make an HTTP request to fetch the roster from the external
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
14 service. The service will need to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
15 changes, so that Prosody can fetch a new roster for that user.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
16
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
17 ## Configuring this module
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
18
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
19 This module relies on `mod_storage_memory` and `mod_block_subscriptions`.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
20
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
21 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
22 `VirtualHost` is being configured, add the following:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
23
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
24 ``` lua
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
25 modules_enabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
26 "http_roster_admin",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
27 "block_subscriptions",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
28 "storage_memory",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
29 "http_files"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
30 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
31 modules_disabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
32 -- Prosody will get the roster from the backend app,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
33 -- so we disable the default roster module.
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
34 "roster"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
35 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
36 storage = { roster = "memory" }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
37 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
38 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
39
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
40 The `http_roster_url` parameter needs to be configured to point to the
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
41 URL in the backend application which returns users' contacts rosters.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
42
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
43 In this URL, the pattern `%s` is replaced by an URL-encoded username.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
44
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
45 When the user *john* then connects to Prosody, and `http_roster_url` is
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
46 set to “http://app.example.org/contacts/%s”, then Prosody will make a
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
47 GET request to http://app.example.org/contacts/john
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
48
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
49 ## Protocol
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
50
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
51 ### Fetching rosters (Prosody to web app)
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
52
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
53 Prosody considers the web application to always hold the most accurate and up-to-date
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
54 version of the user's roster. When a user first connects, Prosody fetches the roster
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
55 from the web application and caches it internally.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
56
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
57 Prosody will make a GET request to the URL specified in Prosody's configuration parameter
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
58 'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
59
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
60 For example, when the user 'john' connects to Prosody, and http_roster_url is set
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
61 to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john".
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
62
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
63 The web app must return a JSON object, where each key is the JID of a contact, and the corresponding
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
64 value is data about that contact.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
65
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
66 If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
67 with the following contents:
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
68
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
69 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
70 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
71 "marie@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
72 "name": "Marie"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
73 },
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
74
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
75 "michael@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
76 "name": "Michael"
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
77 }
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
78 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
79 ```
3006
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
80
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs
Matthew Wild <mwild1@gmail.com>
parents: 2312
diff changeset
81 ### Notifying Prosody of roster changes
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
82
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
83 The external service needs to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
84 changes. To do this, it must make an HTTP POST request to either:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
85
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
86 - http://localhost:5280/roster_admin/refresh
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
87 - https://localhost:5281/roster_admin/refresh
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
88
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
89 Make sure that the "http_files" module is enabled in Prosody's configuration,
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
90 for the above URLs to served.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
91
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
92 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
93 can be configured to reverse proxy those URLs to for example
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
94 https://example.org/http-bind.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
95
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
96 The contents of the POST should be a JSON encoded array of usernames whose
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
97 rosters have changed.
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
98
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
99 For example, if user ‘john’ became friends with ‘aaron’, both john’s
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
100 contact list and aaron’s contact lists have changed:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
101
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
102 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
103 ["john", "aaron"]
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
104 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
105
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
106 When the operation is complete Prosody will reply with a summary of the
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
107 operation - a JSON object containing:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
108
2312
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
109 - **status**: either “ok” (success) or “error” (operation completely failed)
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
110 - **message**: A human-readable message (for logging and debugging purposes)
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
111 - **updated**: The number of rosters successfully updated
234d679076c4 Proper markdown syntax
JC Brand <jcbrand@minddistrict.com>
parents: 2311
diff changeset
112 - **errors**: The number of rosters that failed to update
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
113
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
114 Example:
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
115
3007
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
116 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
117 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
118 "status": "ok",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
119 "message": "roster update complete",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
120 "updated": 2,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
121 "errors": 0
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
122 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints
Kim Alvefur <zash@zash.se>
parents: 3006
diff changeset
123 ```
2161
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
124
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
125 Prosody may also return status codes `400` or `500` in case of errors (such
95a9f2d234da Add mod_http_roster_admin
JC Brand <jc@opkode.com>
parents:
diff changeset
126 as a missing/malformed body).