annotate mod_invites_register/README.markdown @ 5255:001c8fdc91a4

mod_http_oauth2: Add support for the "openid" scope This "openid" scope is there to signal access to the userinfo endpoint, which is needed for OIDC support. We don't actually check this later because the userinfo endpoint only returns info embedded in the token itself, but in the future we may want to check this more carefully.
author Kim Alvefur <zash@zash.se>
date Thu, 16 Mar 2023 17:06:35 +0100
parents 027fb71ad509
children 2f7fff6c8c73
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:
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
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
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 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
11 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
12
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
13 - [mod_invites]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
14 - [mod_invites_adhoc]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
15 - [mod_invites_page]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
16 - [mod_invites_register_web]
4224
816c2fa1ca84 mod_invites*: Also link to mod_invites_api
Kim Alvefur <zash@zash.se>
parents: 4223
diff changeset
17 - [mod_invites_api]
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
18 - [mod_register_apps]
4106
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4106
diff changeset
20 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
21
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 Details
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 =======
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 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
26 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
27 [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
28 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
29
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 **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
31 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
32 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
33
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 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
35 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
36
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 **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
38 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
39
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 # Configuration
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 | Name | Description | Default |
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 |--------------------------|----------------------------------------------------------|---------|
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 | 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
45
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 ## Example: Invite-only registration
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 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
49 invite token.
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 ``` {.lua}
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 allow_registration = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 registration_invite_only = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 ```
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 ## Example: Open registration
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 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
59 an invite token.
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 ``` {.lua}
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 allow_registration = true
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 registration_invite_only = false
d34572047488 mod_invites_register: New module to allow IBR with invite tokens
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 ```