Mercurial > prosody-modules

annotate mod_delegation/README.markdown @ 4923:c83b009b5bc5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add configuration of which stanzas to route to callback Makes it simpler to build APIs that only handle a certain kind of stanzas, letting them be handled by the unhandled stanza handler instead of having to write code to ignore certain kinds of stanzas.
author Kim Alvefur <zash@zash.se>
date Sat, 09 Apr 2022 01:04:25 +0200
parents 679f1834dbdb
children
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)