annotate mod_invites_register/README.markdown @ 5551:8bfcedd93a72

mod_rest: List all error conditions in OpenAPI spec These are not handled by datamanager but by util.stanza and util.error, so they are not represented in the JSON schema file.
author Kim Alvefur <zash@zash.se>
date Sat, 17 Jun 2023 16:26:33 +0200
parents 2f7fff6c8c73
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
3 - 'Stage-Merged'
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Allow account registration using invite tokens'
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ============
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
10 ::: {.alert .alert-info}
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
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: 5141
diff changeset
12 [mod_invites_register][doc:modules:mod_invites_register]. Users of
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
13 Prosody **0.12** and later should not install this version.
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
14 :::
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
15
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 This module is part of the suite of modules that implement invite-based
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 account registration for Prosody. The other modules are:
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18
5482
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
19 - [mod_invites][doc:modules:mod_invites]
2f7fff6c8c73 mod_invites{,_adhoc,_register}: Recommend using version included with prosody
Kim Alvefur <zash@zash.se>
parents: 5141
diff changeset
20 - [mod_invites_adhoc][doc:modules:mod_invites_adhoc]
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
21 - [mod_invites_page]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
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: 4106
diff changeset
24 - [mod_register_apps]
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
26 For details and a full overview, start with the [mod_invites] documentation.
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 Details
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 =======
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 This module allows clients to register an account using an invite ('preauth')
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 token generated by mod_invites. It implements the protocol described at
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 [docs.modernxmpp.org/client/invites](https://docs.modernxmpp.org/client/invites)
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 and [XEP-0401 version 0.3.0](https://xmpp.org/extensions/attic/xep-0401-0.3.0.html).
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 **Note to developers:** the XEP-0401 protocol is expected to change in the future,
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 though Prosody will attempt to maintain backwards compatibility with the 0.3.0 protocol
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 for as long as necessary.
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 This module is also responsible for implementing the optional server-side part
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 of [XEP-0379: Pre-Authenticated Roster Subscriptions](https://xmpp.org/extensions/xep-0379.html).
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 **Note to admins:** Loading this module will disable registration for users
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 without an invite token by default. Control this behaviour
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 # Configuration
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 | Name | Description | Default |
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 |--------------------------|----------------------------------------------------------|---------|
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 | registration_invite_only | Require an invitation token for all account registration | `true` |
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 ## Example: Invite-only registration
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 This setup enables registration **only** for users that have a valid
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 invite token.
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 ``` {.lua}
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 allow_registration = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 registration_invite_only = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 ```
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 ## Example: Open registration
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 This setup allows completely **open registration**, even without
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 an invite token.
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 ``` {.lua}
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 allow_registration = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 registration_invite_only = false
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 ```