author | Kim Alvefur <zash@zash.se> |
Sat, 30 Mar 2019 23:33:58 +0100 | |
changeset 3509 | 106b4ae4469b |
parent 3507 | 882180b459a0 |
child 3510 | 7b1eede1a840 |
permissions | -rw-r--r-- |
3509
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
1 |
--- |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
2 |
summary: Publish to PubSub nodes from via HTTP POST/WebHooks |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
3 |
--- |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
4 |
|
3104 | 5 |
# Introduction |
6 |
||
3509
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
7 |
This module is a fairly generic WebHook receiver that lets you easily |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
8 |
publish data to PubSub using a HTTP POST request. The payload can be |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
9 |
Atom feeds, arbitrary XML, or arbitrary JSON. The type should be |
106b4ae4469b
mod_pubsub_post/README: Mention use as a webhook receiver
Kim Alvefur <zash@zash.se>
parents:
3507
diff
changeset
|
10 |
indicated via the `Content-Type` header. |
3104 | 11 |
|
12 |
``` {.bash} |
|
13 |
curl http://localhost:5280/pubsub_post/princely_musings \ |
|
14 |
-H "Content-Type: application/json" \ |
|
15 |
--data-binary '{"musing":"To be, or not to be: that is the question"}' |
|
16 |
``` |
|
17 |
||
3157
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3156
diff
changeset
|
18 |
- JSON data is wrapped in a [XEP-0335] container. |
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3156
diff
changeset
|
19 |
- An Atom feed may have many `<entry>` and each one is published as |
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3156
diff
changeset
|
20 |
its own PubSub item. |
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3156
diff
changeset
|
21 |
- Other XML is simply published to a randomly named item as-is. |
e0de1fdbc80a
mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents:
3156
diff
changeset
|
22 |
|
3104 | 23 |
# Configuration |
24 |
||
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
25 |
All settings are optional. |
3104 | 26 |
|
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
27 |
## Actor identification |
3104 | 28 |
|
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
29 |
First we have to figure out who is making the request. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
30 |
This is configured on a per-node basis like this: |
3505
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
31 |
|
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
32 |
``` {.lua} |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
33 |
-- Per node secrets |
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
34 |
pubsub_post_actors = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
35 |
princely_musings = "hamlet@denmark.lit" |
3505
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
36 |
} |
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
37 |
pubsub_post_default_actor = "nobody@nowhere.invalid" |
3505
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
38 |
``` |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
39 |
|
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
40 |
`pubsub_post_default_actor` is used when trying to publish to a node |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
41 |
that is not listed in `pubsub_post_actors`. Otherwise the IP address |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
42 |
of the connection is used. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
43 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
44 |
## Authentication |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
45 |
|
3505
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
46 |
[WebSub](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
47 |
Content |
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
48 |
Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution) |
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
49 |
authentication is used. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
50 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
51 |
``` {.lua} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
52 |
pubsub_post_secrets = { |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
53 |
princely_musings = "shared secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
54 |
} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
55 |
pubsub_post_default_secret = "default secret" |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
56 |
``` |
3505
1df139b157fb
mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents:
3260
diff
changeset
|
57 |
|
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
58 |
`pubsub_post_default_secret` is used when trying to publish to a node |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
59 |
that is not listed in `pubsub_post_secrets`. Otherwise the request |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
60 |
proceeds with the previously identified actor. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
61 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
62 |
::: {.alert .alert-danger} |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
63 |
If configured without a secret and a default actor that has permission |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
64 |
to create nodes the service becomes wide open. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
65 |
::: |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
66 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
67 |
## Authorization |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
68 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
69 |
Authorization is handled via pubsub affiliations. Publishing requires an |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
70 |
affiliation with the _publish_ capability, usually `"publisher"`. |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
71 |
|
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
72 |
### Setting up affiliations |
3260
0992c0398783
mod_pubsub_post/README: Add a heading for affiliation related text
Kim Alvefur <zash@zash.se>
parents:
3157
diff
changeset
|
73 |
|
3156
882f7d5c3ce8
mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents:
3155
diff
changeset
|
74 |
Prosodys PubSub module supports [setting affiliations via |
882f7d5c3ce8
mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents:
3155
diff
changeset
|
75 |
XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations), in |
882f7d5c3ce8
mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents:
3155
diff
changeset
|
76 |
trunk since [revision |
3507
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
77 |
384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81), so |
882180b459a0
mod_pubsub_post: Restructure authentication and authorization (BC)
Kim Alvefur <zash@zash.se>
parents:
3506
diff
changeset
|
78 |
affiliations can be configured with a capable client. |
3104 | 79 |
|
80 |
It can however be done from another plugin: |
|
81 |
||
82 |
``` {.lua} |
|
83 |
local mod_pubsub = module:depends("pubsub"); |
|
84 |
local pubsub = mod_pubsub.service; |
|
85 |
||
86 |
pubsub:create("princely_musings", true); |
|
87 |
pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher"); |
|
88 |
``` |