prosody-modules: mod_delegation/README.markdown annotate

annotate mod_delegation/README.markdown @ 5271:3a1df3adad0c

mod_http_oauth2: Allow user to decide which requested scopes to grant These should at the very least be shown to the user, so they can decide whether to grant them. Considered whether to filter the requested scopes down to actually understood scopes that would be granted, but decided that this was a bit complex for a first step, since role role selection and other kinds of scopes are mixed into the same field here.

author	Kim Alvefur <zash@zash.se>
date	Thu, 23 Mar 2023 16:28:08 +0100
parents	679f1834dbdb
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:
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)

Mercurial > prosody-modules

annotate mod_delegation/README.markdown @ 5271:3a1df3adad0c