annotate mod_register_json/README.markdown @ 4249:64aa1d9d70ac

mod_rest: Catch and log errors in callback promise chain From the code it looks like it should be possible to reply to an error stanza, but it did not. Turns out I was saved by my local developer mode module which throws errors if an attempt is made to create an errror reply to an error stanza. However nothing collects this error from the promise, so all I got was confusion.
author Kim Alvefur <zash@zash.se>
date Sun, 15 Nov 2020 16:25:49 +0100
parents 42dac034b2e0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 - 'Stage-Stable'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 summary: 'Token based JSON registration & verification servlet.'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 ...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 ------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 This module let's you activate a httpserver interface to handle data
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 from webforms with POST and Base64 encoded JSON.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 Implementation Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 ----------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 Example Request format:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 POST /your_register_base_url HTTP/1.1
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 Host: yourserveraddress.com:yourchoosenport
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 Content-Type: application/encoded
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 Content-Transfer-Encoding: base64
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 eyJ1c2VybmFtZSI6InVzZXJuYW1lb2ZjaG9pY2UiLCJwYXNzd29yZCI6InRoZXVzZXJwYXNzd29yZCIsImlwIjoidGhlcmVtb3RlYWRkcm9mdGhldXNlciIsIm1haWwiOiJ1c2VybWFpbEB1c2VybWFpbGRvbWFpbi50bGQiLCJhdXRoX3Rva2VuIjoieW91cmF1dGh0b2tlbm9mY2hvaWNlIn0=
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 Where the encoded content is this (example) JSON Array:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
3292
42dac034b2e0 mod_register_json/README: Add syntax hint
Kim Alvefur <zash@zash.se>
parents: 3291
diff changeset
27 ``` {.json}
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
28 {
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
29 "username":"john.smith",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
30 "password":"secret-password",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
31 "ip":"192.168.0.0",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
32 "mail":"john.smith@mail.example.net",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
33 "auth_token":"yourauthtokenofchoice"
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
34 }
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
35 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 Your form implementation needs to pass **all** parameters, the
2876
ea6b5321db50 README files: Fix typos
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
38 auth\_token is needed to prevent misuses, if the request is successful
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 the server will answer with status code 200 and with the body of the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 response containing the token which your web app can send via e-mail to
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 the user to complete the registration.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 Else, it will reply with the following http error codes:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 - 400 - if there's an error syntax;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 - 401 - whenever an username is already pending registration or the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 auth token supplied is invalid;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 - 403 - whenever registration is forbidden (blacklist, filtered mail
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 etc.);
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 - 406 - if the username supplied fails nodeprepping;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 - 409 - if the user already exists, or an user is associated already
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 with the supplied e-mail;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 - 503 - whenever a request is throttled.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 The verification URL path to direct the users to will be:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 **/your-base-path-of-choice/verify/** - on your Prosody's http server.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 The module for now stores a hash of the user's mail address to help slow
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 down duplicated registrations.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 It's strongly encouraged to have the web server communicate with the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 servlet via https.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65 -----
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 Copy the module folder and all its contents (register\_json) into your
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 prosody modules' directory.Add the module your vhost of choice
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 modules\_enabled.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 Hint: pairing with mod\_register\_redirect is helpful, to allow server
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 registrations only via your webform.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
74
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
75 Required configuration:
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
76
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
77 ```
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
78 reg_servlet_auth_token = "your-secret-token"
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
79 ```
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
80
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81 Optional configuration directives:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
83 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 reg_servlet_secure = true -- Have the plugin only process requests on https (default is true)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 reg_servlet_bl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be blacklisted and will not be able to submit registrations.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88 reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 reg_servlet_filtered_mails = { ".*banneddomain.tld", ".*deamailprovider.tld" } -- allows filtering of mail addresses via Lua patterns.
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
90 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 -------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
95 0.9