view 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
line wrap: on
line source

# Introduction

Lets you easily publish data to PubSub using a HTTP POST request. The
payload can be Atom feeds, arbitrary XML, or arbitrary JSON. The type
should be indicated via the `Content-Type` header.

``` {.bash}
curl http://localhost:5280/pubsub_post/princely_musings \
    -H "Content-Type: application/json" \
    --data-binary '{"musing":"To be, or not to be: that is the question"}'
```

-   JSON data is wrapped in a [XEP-0335] container.
-   An Atom feed may have many `<entry>` and each one is published as
    its own PubSub item.
-   Other XML is simply published to a randomly named item as-is.

# Configuration

All settings are optional.

## Actor identification

First we have to figure out who is making the request.
This is configured on a per-node basis like this:

``` {.lua}
-- Per node secrets
pubsub_post_actors = {
    princely_musings = "hamlet@denmark.lit"
}
pubsub_post_default_actor = "nobody@nowhere.invalid"
```

`pubsub_post_default_actor` is used when trying to publish to a node
that is not listed in `pubsub_post_actors`. Otherwise the IP address
of the connection is used.

## Authentication

[WebSub](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated
Content
Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
authentication is used.

``` {.lua}
pubsub_post_secrets = {
    princely_musings = "shared secret"
}
pubsub_post_default_secret = "default secret"
```

`pubsub_post_default_secret` is used when trying to publish to a node
that is not listed in `pubsub_post_secrets`. Otherwise the request
proceeds with the previously identified actor.

::: {.alert .alert-danger}
If configured without a secret and a default actor that has permission
to create nodes the service becomes wide open.
:::

## Authorization

Authorization is handled via pubsub affiliations. Publishing requires an
affiliation with the _publish_ capability, usually `"publisher"`.

### Setting up affiliations

Prosodys PubSub module supports [setting affiliations via
XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations), in
trunk since [revision
384ef9732b81](https://hg.prosody.im/trunk/rev/384ef9732b81), so
affiliations can be configured with a capable client.

It can however be done from another plugin:

``` {.lua}
local mod_pubsub = module:depends("pubsub");
local pubsub = mod_pubsub.service;

pubsub:create("princely_musings", true);
pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
```