Mercurial > prosody-modules
annotate mod_register_json/README.markdown @ 3910:49efd1323a1b
mod_rest: Add support for token authentication
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Wed, 26 Feb 2020 18:36:40 +0000 |
parents | 42dac034b2e0 |
children |
rev | line source |
---|---|
1803 | 1 --- |
2 labels: | |
3 - 'Stage-Stable' | |
4 summary: 'Token based JSON registration & verification servlet.' | |
5 ... | |
6 | |
7 Introduction | |
8 ------------ | |
9 | |
10 This module let's you activate a httpserver interface to handle data | |
11 from webforms with POST and Base64 encoded JSON. | |
12 | |
13 Implementation Details | |
14 ---------------------- | |
15 | |
16 Example Request format: | |
17 | |
18 POST /your_register_base_url HTTP/1.1 | |
19 Host: yourserveraddress.com:yourchoosenport | |
20 Content-Type: application/encoded | |
21 Content-Transfer-Encoding: base64 | |
22 | |
23 eyJ1c2VybmFtZSI6InVzZXJuYW1lb2ZjaG9pY2UiLCJwYXNzd29yZCI6InRoZXVzZXJwYXNzd29yZCIsImlwIjoidGhlcmVtb3RlYWRkcm9mdGhldXNlciIsIm1haWwiOiJ1c2VybWFpbEB1c2VybWFpbGRvbWFpbi50bGQiLCJhdXRoX3Rva2VuIjoieW91cmF1dGh0b2tlbm9mY2hvaWNlIn0= | |
24 | |
25 Where the encoded content is this (example) JSON Array: | |
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 | 36 |
37 Your form implementation needs to pass **all** parameters, the | |
2876 | 38 auth\_token is needed to prevent misuses, if the request is successful |
1803 | 39 the server will answer with status code 200 and with the body of the |
40 response containing the token which your web app can send via e-mail to | |
41 the user to complete the registration. | |
42 | |
43 Else, it will reply with the following http error codes: | |
44 | |
45 - 400 - if there's an error syntax; | |
46 - 401 - whenever an username is already pending registration or the | |
47 auth token supplied is invalid; | |
48 - 403 - whenever registration is forbidden (blacklist, filtered mail | |
49 etc.); | |
50 - 406 - if the username supplied fails nodeprepping; | |
51 - 409 - if the user already exists, or an user is associated already | |
52 with the supplied e-mail; | |
53 - 503 - whenever a request is throttled. | |
54 | |
55 The verification URL path to direct the users to will be: | |
56 **/your-base-path-of-choice/verify/** - on your Prosody's http server. | |
57 | |
58 The module for now stores a hash of the user's mail address to help slow | |
59 down duplicated registrations. | |
60 | |
61 It's strongly encouraged to have the web server communicate with the | |
62 servlet via https. | |
63 | |
64 Usage | |
65 ----- | |
66 | |
67 Copy the module folder and all its contents (register\_json) into your | |
68 prosody modules' directory.Add the module your vhost of choice | |
69 modules\_enabled. | |
70 | |
71 Hint: pairing with mod\_register\_redirect is helpful, to allow server | |
72 registrations only via your webform. | |
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 | 81 Optional configuration directives: |
82 | |
3291
4c3230c22c18
mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents:
2876
diff
changeset
|
83 ``` |
1803 | 84 reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account) |
85 reg_servlet_secure = true -- Have the plugin only process requests on https (default is true) | |
86 reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address. | |
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. | |
88 reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling. | |
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 | 91 |
92 Compatibility | |
93 ------------- | |
94 | |
95 0.9 |