prosody-modules
750d64c47ec6
mod_privilege/README.md

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

Software / code / prosody-modules

Comparison

mod_privilege/README.md @ 6211:750d64c47ec6 draft

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 18 Mar 2025 00:31:36 +0700
parent 6003:fe081789f7b5
comparison
equal deleted inserted replaced
6210:24316a399978 6211:750d64c47ec6
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: 'XEP-0356 (Privileged Entity) implementation'
5 ...
6
7 Introduction
8 ============
9
10 Privileged Entity is an extension which allows entity/component to have
11 privileged access to server (set/get roster, send message on behalf of server,
12 send IQ stanza on behalf of user, access presence information). It can be used
13 to build services independently of server (e.g.: PEP service).
14
15 Details
16 =======
17
18 You can have all the details by reading the
19 [XEP-0356](http://xmpp.org/extensions/xep-0356.html).
20
21 Only the latest version of the XEP is implemented (using namespace
22 `urn:xmpp:privilege:2`), if your component use an older version, please update.
23
24 Note that roster permission is not fully implemented yet, roster pushes are not yet sent
25 to privileged entity.
26
27 Usage
28 =====
29
30 To use the module, like usual add **"privilege"** to your
31 modules\_enabled. Note that if you use it with a local component, you
32 also need to activate the module in your component section:
33
34 modules_enabled = {
35 [...]
36
37 "privilege";
38 }
39
40 [...]
41
42 Component "pubsub.yourdomain.tld"
43 component_secret = "yourpassword"
44 modules_enabled = {"privilege"}
45
46 then specify privileged entities **in your host section** like that:
47
48 VirtualHost "yourdomain.tld"
49
50 privileged_entities = {
51 ["romeo@montaigu.lit"] = {
52 roster = "get";
53 presence = "managed_entity";
54 },
55 ["juliet@capulet.lit"] = {
56 roster = "both";
57 message = "outgoing";
58 presence = "roster";
59 },
60 ["pubsub.yourdomain.tld"] = {
61 roster = "get";
62 message = "outgoing";
63 presence = "roster";
64 iq = {
65 ["http://jabber.org/protocol/pubsub"] = "set";
66 };
67 },
68 }
69
70 Here *romeo@montaigu.lit* can **get** roster of anybody on the host, and will
71 **have presence for any user** of the host, while *juliet@capulet.lit* can
72 **get** and **set** a roster, **send messages** on behalf of the server, and
73 **access presence of anybody linked to the host** (not only people on the
74 server, but also people in rosters of users of the server).
75
76 *pubsub.yourdomain.tld* is a Pubsub/PEP component which can **get** roster of
77 anybody on the host, **send messages** on the behalf of the server, **access
78 presence of anybody linked to the host**, and **send IQ stanza of type "set" for
79 the namespace "http://jabber.org/protocol/pubsub"** (this can be used to
80 implement XEP-0376 "Pubsub Account Management").
81
82 **/!\\ Be extra careful when you give a permission to an entity/component, it's
83 a powerful access, only do it if you absolutely trust the component/entity, and
84 you know where the software is coming from**
85
86 Configuration
87 =============
88
89 roster
90 ------
91
92 All the permissions give access to all accounts of the virtual host.
93
94 -------- ------------------------------------------------ ----------------------
95 roster none *(default)* No access to rosters
96 get Allow **read** access to rosters
97 set Allow **write** access to rosters
98 both Allow **read** and **write** access to rosters
99 -------- ------------------------------------------------ ----------------------
100
101 Note that roster implementation is incomplete at the moment, roster pushes are not yet
102 send to privileged entity.
103
104 message
105 -------
106
107 ------------------ ------------------------------------------------------------
108 none *(default)* Can't send message from server
109 outgoing Allow to send message on behalf of server (from bare jids)
110 ------------------ ------------------------------------------------------------
111
112 presence
113 --------
114
115 ------------------ ------------------------------------------------------------------------------------------------
116 none *(default)* Do not have extra presence information
117 managed\_entity Receive presence stanzas (except subscriptions) from host users
118 roster Receive all presence stanzas (except subsciptions) from host users and people in their rosters
119 ------------------ ------------------------------------------------------------------------------------------------
120
121 iq
122 --
123
124 IQ permission is a table mapping allowed namespaces to allowed stanza type. When
125 a namespace is specified, IQ stanza of the specified type (see below) can be
126 sent if and only if the first child element of the IQ stanza has the specified
127 namespace. See https://xmpp.org/extensions/xep-0356.html#iq for details.
128
129 Allowed stanza type:
130
131 -------- -------------------------------------------
132 get Allow IQ stanza of type **get**
133 set Allow IQ stanza of type **set**
134 both Allow IQ stanza of type **get** and **set**
135 -------- -------------------------------------------
136
137 Compatibility
138 =============
139
140 If you use it with Prosody 0.9 and with a component, you need to patch
141 core/mod\_component.lua to fire a new signal. To do it, copy the
142 following patch in a, for example, /tmp/component.patch file:
143
144 ``` {.patch}
145 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
146 --- a/plugins/mod_component.lua
147 +++ b/plugins/mod_component.lua
148 @@ -85,6 +85,7 @@
149 session.type = "component";
150 module:log("info", "External component successfully authenticated");
151 session.send(st.stanza("handshake"));
152 + module:fire_event("component-authenticated", { session = session });
153
154 return true;
155 end
156 ```
157
158 Then, at the root of prosody, enter:
159
160 `patch -p1 < /tmp/component.patch`
161
162 ----- --------------------------------------------------
163 trunk Works
164 0.12 Works
165 0.11 Works
166 0.10 Works
167 0.9 Need a patched core/mod\_component.lua (see above)
168 ----- --------------------------------------------------
169
170 Note
171 ====
172
173 This module is often used with mod\_delegation (c.f. XEP for more details)