prosody-modules
1df139b157fb
mod_pubsub_post/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_pubsub_post/README.markdown @ 3501:1df139b157fb

mod_pubsub_post: Add support for WebSub authentication
author Kim Alvefur <zash@zash.se>
date Fri, 24 Aug 2018 14:52:09 +0200
parent 3256:0992c0398783
child 3502:42e9e3c5eb02
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 # Introduction
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 Lets you easily publish data to PubSub using a HTTP POST request. The
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 payload can be Atom feeds, arbitrary XML, or arbitrary JSON. The type
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 should be indicated via the `Content-Type` header.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 ``` {.bash}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 curl http://localhost:5280/pubsub_post/princely_musings \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 -H "Content-Type: application/json" \
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 --data-binary '{"musing":"To be, or not to be: that is the question"}'
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
3153
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
13 - 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: 3152
diff changeset
14 - 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: 3152
diff changeset
15 its own PubSub item.
e0de1fdbc80a mod_pubsub_post/README: Describe what happens to different data types
Kim Alvefur <zash@zash.se>
parents: 3152
diff changeset
16 - 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: 3152
diff changeset
17
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 # Configuration
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 ## Authentication
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 Authentication can be handled in two different ways.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24 ### None
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 pubsub_post_actor = "superuser"
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 The module uses an internal actor that has all privileges and can always
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 do everything. It is strongly suggested that you do not expose this to
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 the Internet. *Maybe* it shouldn't be the default...
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 ### IP
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 pubsub_post_actor = "request.ip"
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 ```
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 Uses the IP address from the HTTP request as actor, which means this
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 pseudo-JID must be given a 'publisher' affiliation. This should work
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 nicely with the `autocreate_on_publish` setting, where the first actor
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 to attempt to publish to a non-existant node becomes owner of it, which
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44 includes publishing rights.
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45
3501
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
46 ## WebSub
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
47
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
48 ``` {.lua}
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
49 -- Per node secrets
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
50 pubsub_post_secrets = {
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
51 my_node = "shared secret"
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
52 }
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
53
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
54 -- Same secret for all nodes
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
55 pubsub_post_secret = "shared secret"
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
56 ```
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
57
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
58 This enables the
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
59 [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: 3256
diff changeset
60 Content
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
61 Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
62 authentication method, where payloads are signed using a shared secret.
1df139b157fb mod_pubsub_post: Add support for WebSub authentication
Kim Alvefur <zash@zash.se>
parents: 3256
diff changeset
63
3256
0992c0398783 mod_pubsub_post/README: Add a heading for affiliation related text
Kim Alvefur <zash@zash.se>
parents: 3153
diff changeset
64 ## Setting up affiliations
0992c0398783 mod_pubsub_post/README: Add a heading for affiliation related text
Kim Alvefur <zash@zash.se>
parents: 3153
diff changeset
65
3152
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents: 3151
diff changeset
66 Prosodys PubSub module supports [setting affiliations via
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents: 3151
diff changeset
67 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: 3151
diff changeset
68 trunk since [revision
882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now
Kim Alvefur <zash@zash.se>
parents: 3151
diff changeset
69 384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81).
3100
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 It can however be done from another plugin:
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74 local mod_pubsub = module:depends("pubsub");
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 local pubsub = mod_pubsub.service;
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77 pubsub:create("princely_musings", true);
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
0422fb55cc37 mod_pubsub_post: Add a README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79 ```