Mercurial > prosody-modules
annotate mod_privilege/README.markdown @ 4913:3ddab718f717
mod_privilege: update to v0.4:
- now the namespace "urn:xmpp:privilege:2" is exclusively used
- IQ permission implementation
- README update
roster pushes are not implemented yet
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Wed, 11 May 2022 12:43:26 +0200 |
| parents | 8dda3d7d616f |
| children |
| 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: |
| 4913 | 3 - 'Stage-Beta' |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
4 summary: 'XEP-0356 (Privileged Entity) implementation' |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
5 ... |
| 1782 | 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 | 9 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
10 Privileged Entity is an extension which allows entity/component to have |
| 4913 | 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). | |
| 1782 | 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 | 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 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
19 [XEP-0356](http://xmpp.org/extensions/xep-0356.html). |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
20 |
| 4913 | 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 | |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
27 Usage |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
28 ===== |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
29 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
30 To use the module, like usual add **"privilege"** to your |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
31 modules\_enabled. Note that if you use it with a local component, you |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
32 also need to activate the module in your component section: |
| 1782 | 33 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
34 modules_enabled = { |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
35 [...] |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
36 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
37 "privilege"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
38 } |
| 1782 | 39 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
40 [...] |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
41 |
| 4913 | 42 Component "pubsub.yourdomain.tld" |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
43 component_secret = "yourpassword" |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
44 modules_enabled = {"privilege"} |
| 1782 | 45 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
46 then specify privileged entities **in your host section** like that: |
| 1782 | 47 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
48 VirtualHost "yourdomain.tld" |
| 1782 | 49 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
50 privileged_entities = { |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
51 ["romeo@montaigu.lit"] = { |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
52 roster = "get"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
53 presence = "managed_entity"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
54 }, |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
55 ["juliet@capulet.lit"] = { |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
56 roster = "both"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
57 message = "outgoing"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
58 presence = "roster"; |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
59 }, |
| 4913 | 60 ["pubsub.yourdomain.tld"] = { |
| 61 roster = "get"; | |
| 62 message = "outgoing"; | |
| 63 presence = "roster"; | |
| 64 iq = { | |
| 65 ["http://jabber.org/protocol/pubsub"] = "set"; | |
| 66 }; | |
| 67 }, | |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
68 } |
| 1782 | 69 |
| 4913 | 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). | |
| 1782 | 75 |
| 4913 | 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** | |
| 1782 | 85 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
86 Configuration |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
87 ============= |
| 1782 | 88 |
| 4913 | 89 roster |
| 90 ------ | |
| 91 | |
| 1782 | 92 All the permissions give access to all accounts of the virtual host. |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
93 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
94 -------- ------------------------------------------------ ---------------------- |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
95 roster none *(default)* No access to rosters |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
96 get Allow **read** access to rosters |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
97 set Allow **write** access to rosters |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
98 both Allow **read** and **write** access to rosters |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
99 -------- ------------------------------------------------ ---------------------- |
| 1782 | 100 |
| 4913 | 101 Note that roster implementation is incomplete at the moment, roster pushes are not yet |
| 102 send to privileged entity. | |
| 103 | |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
104 message |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
105 ------- |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
106 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
107 ------------------ ------------------------------------------------------------ |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
108 none *(default)* Can't send message from server |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
109 outgoing Allow to send message on behalf of server (from bare jids) |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
110 ------------------ ------------------------------------------------------------ |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
111 |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
112 presence |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
113 -------- |
| 1782 | 114 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
115 ------------------ ------------------------------------------------------------------------------------------------ |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
116 none *(default)* Do not have extra presence information |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
117 managed\_entity Receive presence stanzas (except subscriptions) from host users |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
118 roster Receive all presence stanzas (except subsciptions) from host users and people in their rosters |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
119 ------------------ ------------------------------------------------------------------------------------------------ |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
120 |
| 4913 | 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 | |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
137 Compatibility |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
138 ============= |
| 1782 | 139 |
| 1992 | 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 | |
| 4913 | 162 ----- -------------------------------------------------- |
| 163 trunk Works | |
| 164 0.12 Works | |
| 165 0.11 Works | |
| 1992 | 166 0.10 Works |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
167 0.9 Need a patched core/mod\_component.lua (see above) |
| 4913 | 168 ----- -------------------------------------------------- |
| 1782 | 169 |
|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
170 Note |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
171 ==== |
|
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
172 |
| 4913 | 173 This module is often used with mod\_delegation (c.f. XEP for more details) |