prosody-modules: mod_invites/README.markdown annotate

annotate mod_invites/README.markdown @ 5643:73c3d5bfce3e

mod_http_oauth2: Allow 'login_hint' as a substitute for OIDC 'select_account' prompt If the OIDC 'prompt' parameter does not contain the 'select_account' then it wants us to skip account selection, which means we have to figure which account to authenticate somehow. One way could be have this stored in a cookie from a previous successful login. Another way would be to have the account passed as a hint, which is what we add here.

author	Kim Alvefur <zash@zash.se>
date	Sat, 09 Sep 2023 21:42:24 +0200
parents	2f7fff6c8c73
children

rev	line source
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	1 ---
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	2 labels:
5482 2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	3 - 'Stage-Merged'
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	4 summary: 'Invite management module for Prosody'
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	5 ...
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	6
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	7 Introduction
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	8 ============
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	9
5482 2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	10 ::: {.alert .alert-info}
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	11 This module has been merged into Prosody as
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	12 [mod_invites][doc:modules:mod_invites]. Users of Prosody 0.12
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	13 and later should not install this version.
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	14 :::
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	15
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	16 This module is part of the suite of modules that implement invite-based
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	17 account registration for Prosody. The other modules are:
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	18
5482 2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	19 - [mod_invites_adhoc][doc:modules:mod_invites_adhoc]
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody Kim Alvefur <zash@zash.se> parents: 4224 diff changeset	20 - [mod_invites_register][doc:modules:mod_invites_register]
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4097 diff changeset	21 - [mod_invites_page]
4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4097 diff changeset	22 - [mod_invites_register_web]
4224 816c2fa1ca84 mod_invites: Also link to mod_invites_api Kim Alvefur <zash@zash.se>* parents: 4223 diff changeset	23 - [mod_invites_api]
4223 4ec755c13e9b mod_invites: Link to each other Kim Alvefur <zash@zash.se>* parents: 4097 diff changeset	24 - [mod_register_apps]
3776 80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	25
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	26 This module manages the creation and consumption of invite codes for the
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	27 host(s) it is loaded onto. It currently does not expose any admin/user-facing
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	28 functionality (though in the future it will probably gain a way to view/manage
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	29 pending invites).
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	30
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	31 Instead, other modules can use the API from this module to create invite tokens
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	32 which can be used to e.g. register accounts or create automatic subscription
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	33 approvals.
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	34
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	35 This module should not be confused with the similarly named mod_invite (note the
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	36 missing 's'!). That module was a precursor to this one that helped test and prove
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	37 the concept of invite-based registration, and is now deprecated.
3776 80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	38
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	39 # Configuration
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	40
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	41 This module exposes just one option - the length of time that a generated invite
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	42 should be valid for by default.
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	43
3780 824447fc7759 mod_invites/README: Fix code block syntax Kim Alvefur <zash@zash.se> parents: 3776 diff changeset	44 ``` {.lua}
3776 80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	45 -- Configure the number of seconds a token is valid for (default 7 days)
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	46 invite_expiry = 86400 * 7
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	47 ```
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	48
4097 96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	49 # Invites setup
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	50
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	51 For a fully-featured invite-based setup, the following provides an example
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	52 configuration:
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	53
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	54 ``` {.lua}
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	55 -- Specify the external URL format of the invite links
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	56
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	57 VirtualHost "example.com"
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	58 invites_page = "https://example.com/invite?{invite.token}"
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	59 http_external_url = "https://example.com/"
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	60 http_paths = {
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	61 invites_page = "/invite";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	62 invites_register_web = "/register";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	63 }
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	64 modules_enabled = {
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	65 "invites";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	66 "invites_adhoc";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	67 "invites_page";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	68 "invites_register";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	69 "invites_register_web";
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	70
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	71 "http_libjs"; -- See 'external dependencies' below
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	72 }
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	73 ```
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	74
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	75 Restart Prosody and create a new invite using an ad-hoc command in an XMPP client connected
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	76 to your admin account, or use the command line:
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	77
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	78 prosodyctl mod_invites generate example.com
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	79
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	80 ## External dependencies
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	81
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	82 The default HTML templates for the web-based modules depend on some CSS and Javascript
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	83 libraries. They expect these to be available at `https://example.com/share`. An easy
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	84 way of doing this if you are on Debian 10 (buster) is to enable mod_http_libjs and install
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	85 the following packages:
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	86
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	87 apt install libjs-bootstrap4 libjs-jquery
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	88
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	89 On other systems you will need to manually put these libraries somewhere on the filesystem
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	90 that Prosody can read, and serve them using mod_http_libjs with a custom `libjs_path`
96838617695a mod_invites: Update documentation Matthew Wild <mwild1@gmail.com> parents: 3780 diff changeset	91 setting.
3776 80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	92
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	93 # Compatibility
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	94
80830d97da81 mod_invites: New module providing an API to create/manage invite tokens Matthew Wild <mwild1@gmail.com> parents: diff changeset	95 0.11 and later.

Mercurial > prosody-modules

annotate mod_invites/README.markdown @ 5643:73c3d5bfce3e