prosody-modules
2542fd80cd15
mod_delegation/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_delegation/README.markdown @ 4895:2542fd80cd15

mod_turn_external: Fix type of config option (thanks mirux) There was a separate boolean option to enable TLS before, but it was merged with the port number option and it seems the typed API interface got confused. Backport of trunk rev aa7a8aa64d3f
author Kim Alvefur <zash@zash.se>
date Tue, 15 Feb 2022 21:51:52 +0100
parent 4709:679f1834dbdb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
2759
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents: 1993
diff changeset
3 - 'Stage-Beta'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 summary: 'XEP-0355 (Namespace Delegation) implementation'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
5 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
10 Namespace Delegation is an extension which allows server to delegate some
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
11 features handling to an entity/component. Typical use case is an external PEP
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
12 service, but it can be used more generally when your preferred server lack one
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
13 internal feature, and you found an external component which can do it.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
16 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
18 You can have all the details by reading the
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
19 [XEP-0355](http://xmpp.org/extensions/xep-0355.html). Only the admin mode is
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
20 implemented so far.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
21
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 =====
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
25 To use the module, like usual add **"delegation"** to your *modules\_enabled*.
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
26 Note that if you use it with a local component, you also need to activate the
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
27 module in your component section:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
29 modules_enabled = {
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
30 [...]
2759
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents: 1993
diff changeset
31
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
32 "delegation";
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
33 }
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
34
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
35 [...]
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
37 Component "youcomponent.yourdomain.tld"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
38 component_secret = "yourpassword"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
39 modules_enabled = {"delegation"}
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
41 then specify delegated namespaces **in your host section** like that:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
42
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
43 VirtualHost "yourdomain.tld"
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
45 delegations = {
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
46 ["urn:xmpp:mam:2"] = {
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
47 filtering = {"node"};
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
48 jid = "pubsub.yourdomain.tld";
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
49 },
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
50 ["http://jabber.org/protocol/pubsub"] = {
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
51 jid = "pubsub.yourdomain.tld";
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
52 },
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
53 ["http://jabber.org/protocol/pubsub#owner"] = {
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
54 jid = "pubsub.yourdomain.tld";
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
55 },
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
56 ["urn:xmpp:delegation:2:bare:disco#info:*"] = {
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
57 jid = "pubsub.yourdomain.tld";
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
58 },
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
59 ["urn:xmpp:delegation:2:bare:disco#items:*"] = {
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
60 jid = "pubsub.yourdomain.tld";
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
61 },
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
62
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
63 }
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
65 Here all MAM requests with a "node" attribute (i.e. all MAM pubsub request) will
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
66 be delegated to pubsub.yourdomain.tld. Similarly, all pubsub request to the host
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
67 (i.e. the PEP requests) will be delegated to pubsub.yourdomain.tld. Check the
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
68 XEP for the meaning of "urn:xmpp:delegation:2:bare:disco#info:*" and
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
69 "urn:xmpp:delegation:2:bare:disco#items:*".
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
70
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
71 **/!\ Be extra careful when you give a delegation to an entity/component, it's a
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
72 powerful access, only do it if you absolutely trust the component/entity, and
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
73 you know where the software is coming from**
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
75 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
76 =============
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
77
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
78 The configuration is done with a table which map delegated namespace to
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
79 namespace data. Namespace data MUST have a **jid** (in the form **jid =
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
80 "delegated@domain.tld"**) and MAY have an additional **filtering** array. If
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
81 filtering is present, request with attributes in the array will be delegated,
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
82 others will be treated normally (i.e. by Prosody).
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
84 If you are not a developer, the delegated namespace(s)/attribute(s) are most
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
85 probably specified with the external component/entity you want to use.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
87 The pseudo-namespace `http://jabber.org/protocol/disco#items:*` is used to
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
88 delegate remaining disco#items (i.e. items nodes not already handled by Prosody
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
89 itself).
2759
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents: 1993
diff changeset
90
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
91 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
92 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93
1993
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
94 If you use it with Prosody 0.9 and a component, you need to patch
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
95 core/mod\_component.lua to fire a new signal. To do it, copy the following patch
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
96 in a, for example, /tmp/component.patch file:
1993
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
97
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
98 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
99 --- a/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
100 +++ b/plugins/mod_component.lua
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
101 @@ -85,6 +85,7 @@
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
102 session.type = "component";
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
103 module:log("info", "External component successfully authenticated");
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
104 session.send(st.stanza("handshake"));
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
105 + module:fire_event("component-authenticated", { session = session });
2759
4bf60727459b mod_delegation: added disco#items:* in doc and changed status to Stage-Beta
Goffi <goffi@goffi.org>
parents: 1993
diff changeset
106
1993
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
107 return true;
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
108 end
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
109
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
110 Then, at the root of prosody, enter:
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
111
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
112 `patch -p1 < /tmp/component.patch`
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
113
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
114 ----- ----------------------------------------------------
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
115 0.11 Works
1993
66aaf7c3cb29 mod_delegation: updated README
Goffi <goffi@goffi.org>
parents: 1803
diff changeset
116 0.10 Works
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
117 0.9 Need a patched core/mod\_component.lua (see above)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
118 ----- ----------------------------------------------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
120 Note
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
121 ====
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
122
4709
679f1834dbdb mod_delegation: update to XEP-0355 v0.5
Goffi <goffi@goffi.org>
parents: 2876
diff changeset
123 This module is often used with mod\_privilege (c.f. XEP for more details)