prosody-modules: mod_pubsub_post/README.markdown annotate

annotate mod_pubsub_post/README.markdown @ 3503:882180b459a0

mod_pubsub_post: Restructure authentication and authorization (BC) This deprecates the default "superuser" actor model and makes the default equivalent to the previous "request.id". A single actor and secret per node is supported because HTTP and WebHooks don't normally include any authorization identity. Allowing authentication bypass when no secret is given should be relatively safe when the actor is unprivileged, as will be unless explicitly configured otherwise.

author	Kim Alvefur <zash@zash.se>
date	Sat, 30 Mar 2019 21:16:13 +0100
parents	42e9e3c5eb02
children	106b4ae4469b

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
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	20 All settings are optional.
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	21
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	22 ## Actor identification
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	23
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	24 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: 3502 diff changeset	25 This is configured on a per-node basis like this:
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	26
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	27 ``` {.lua}
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	28 -- Per node secrets
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	29 pubsub_post_actors = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	30 princely_musings = "hamlet@denmark.lit"
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	31 }
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	32 pubsub_post_default_actor = "nobody@nowhere.invalid"
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	33 ```
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	34
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	35 `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: 3502 diff changeset	36 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: 3502 diff changeset	37 of the connection is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	38
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	39 ## Authentication
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	40
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	41 [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	42 Content
1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	43 Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	44 authentication is used.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	45
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	46 ``` {.lua}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	47 pubsub_post_secrets = {
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	48 princely_musings = "shared secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	49 }
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	50 pubsub_post_default_secret = "default secret"
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	51 ```
3501 1df139b157fb mod_pubsub_post: Add support for WebSub authentication Kim Alvefur <zash@zash.se> parents: 3256 diff changeset	52
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	53 `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: 3502 diff changeset	54 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: 3502 diff changeset	55 proceeds with the previously identified actor.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	56
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	57 ::: {.alert .alert-danger}
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	58 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: 3502 diff changeset	59 to create nodes the service becomes wide open.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	60 :::
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	61
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	62 ## Authorization
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	63
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	64 Authorization is handled via pubsub affiliations. Publishing requires an
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	65 affiliation with the _publish_ capability, usually `"publisher"`.
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	66
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	67 ### Setting up affiliations
3256 0992c0398783 mod_pubsub_post/README: Add a heading for affiliation related text Kim Alvefur <zash@zash.se> parents: 3153 diff changeset	68
3152 882f7d5c3ce8 mod_pubsub_post/README: Affiliation management in trunk now Kim Alvefur <zash@zash.se> parents: 3151 diff changeset	69 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	70 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	71 trunk since [revision
3503 882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	72 384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81), so
882180b459a0 mod_pubsub_post: Restructure authentication and authorization (BC) Kim Alvefur <zash@zash.se> parents: 3502 diff changeset	73 affiliations can be configured with a capable client.
3100 0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	74
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	75 It can however be done from another plugin:
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 ``` {.lua}
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	78 local mod_pubsub = module:depends("pubsub");
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	79 local pubsub = mod_pubsub.service;
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	80
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	81 pubsub:create("princely_musings", true);
0422fb55cc37 mod_pubsub_post: Add a README Kim Alvefur <zash@zash.se> parents: diff changeset	82 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	83 ```

Mercurial > prosody-modules

annotate mod_pubsub_post/README.markdown @ 3503:882180b459a0