prosody-modules: mod_privilege/README.markdown annotate

annotate mod_privilege/README.markdown @ 4832:bfd4af4caddc

mod_password_policy: Support for additional policies provided by other modules E.g. check a password contains an uppercase character: module:provides("password-policy", { name = "contains_uppercase"; check_password = function (password, policy) return (policy ~= true) or (not not password:match("%u")); end; }) Config: password_policy = { contains_uppercase = true; }

author	Matthew Wild <mwild1@gmail.com>
date	Wed, 22 Dec 2021 14:48:46 +0000
parents	8dda3d7d616f
children	3ddab718f717

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:
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	3 - 'Stage-Alpha'
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 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
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
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	11 privileged access to server (set/get roster, send message on behalf of
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	12 server, access presence informations). It can be used to build services
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	13 independently of server (e.g.: PEP service).
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
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
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	21 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	22 =====
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	23
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	24 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	25 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	26 also need to activate the module in your component section:
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	27
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	28 modules_enabled = {
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
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	31 "privilege";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	32 }
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	33
1803 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
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	36 Component "youcomponent.yourdomain.tld"
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	37 component_secret = "yourpassword"
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	38 modules_enabled = {"privilege"}
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	39
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	40 then specify privileged entities in your host section like that:
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	41
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	42 VirtualHost "yourdomain.tld"
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	43
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	44 privileged_entities = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	45 ["romeo@montaigu.lit"] = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	46 roster = "get";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	47 presence = "managed_entity";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	48 },
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	49 ["juliet@capulet.lit"] = {
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	50 roster = "both";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	51 message = "outgoing";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	52 presence = "roster";
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	53 },
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	54 }
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	55
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	56 Here romeo@montaigu.lit can get roster of anybody on the host, and
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	57 will have presence for any user of the host, while
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	58 juliet@capulet.lit can get and set a roster, send messages
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	59 on the behalf of the server, and **access presence of anybody linked to
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	60 the host** (not only people on the server, but also people in rosters of
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	61 users of the server).
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	62
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	63 **/! Be extra careful when you give a permission to an entity/component,
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	64 it's a powerful access, only do it if you absoly trust the
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	65 component/entity, and you know where the software is coming from**
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	66
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	67 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	68 =============
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	69
29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	70 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	71
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	72 -------- ------------------------------------------------ ----------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	73 roster none (default) No access to rosters
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	74 get Allow read access to rosters
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	75 set Allow write access to rosters
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	76 both Allow read and write access to rosters
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	77 -------- ------------------------------------------------ ----------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	78
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	79 message
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	80 -------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	81
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	82 ------------------ ------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	83 none (default) Can't send message from server
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	84 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	85 ------------------ ------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	86
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	87 presence
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	88 --------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	89
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	90 ------------------ ------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	91 none (default) Do not have extra presence information
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	92 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	93 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	94 ------------------ ------------------------------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	95
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	96 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	97 =============
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	98
1992 8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	99 If you use it with Prosody 0.9 and with a component, you need to patch
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	100 core/mod\_component.lua to fire a new signal. To do it, copy the
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	101 following patch in a, for example, /tmp/component.patch file:
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	102
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	103 ``` {.patch}
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	104 diff --git a/plugins/mod_component.lua b/plugins/mod_component.lua
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	105 --- a/plugins/mod_component.lua
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	106 +++ b/plugins/mod_component.lua
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	107 @@ -85,6 +85,7 @@
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	108 session.type = "component";
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	109 module:log("info", "External component successfully authenticated");
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	110 session.send(st.stanza("handshake"));
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	111 + module:fire_event("component-authenticated", { session = session });
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	112
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	113 return true;
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	114 end
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	115 ```
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	116
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	117 Then, at the root of prosody, enter:
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	118
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	119 `patch -p1 < /tmp/component.patch`
8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	120
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	121 ----- ----------------------------------------------------
1992 8dda3d7d616f mod_privilege: updated README Goffi <goffi@goffi.org> parents: 1803 diff changeset	122 0.10 Works
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	123 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	124 ----- ----------------------------------------------------
1782 29f3d6b7ad16 Import wiki pages Kim Alvefur <zash@zash.se> parents: diff changeset	125
1803 4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	126 Note
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	127 ====
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	128
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	129 This module is often used with mod\_delegation (c.f. XEP for more
4d73a1a6ba68 Convert all wiki pages to Markdown Kim Alvefur <zash@zash.se> parents: 1782 diff changeset	130 details)

Mercurial > prosody-modules

annotate mod_privilege/README.markdown @ 4832:bfd4af4caddc