annotate mod_register_json.wiki @ 502:3c81d8a9f1e2

Documentation for the new mod_admin_message module.
author mikael.berthe@gmail.com
date Sun, 25 Jan 2015 19:07:33 +0000
parents 37502ad2fcb8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
1 #summary Token based JSON registration & verification servlet.
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
2 #labels Stage-Stable
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
3
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
4 = Introduction =
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
5
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
6 This module let's you activate a httpserver interface to handle data from webforms with POST and Base64 encoded JSON.
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
7
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
8 = Implementation Details =
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
9
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
10 Example Request format:
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
11
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
12 {{{
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
13 POST /your_register_base_url HTTP/1.1
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
14 Host: yourserveraddress.com:yourchoosenport
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
15 Content-Type: application/encoded
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
16 Content-Transfer-Encoding: base64
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
17
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
18 eyJ1c2VybmFtZSI6InVzZXJuYW1lb2ZjaG9pY2UiLCJwYXNzd29yZCI6InRoZXVzZXJwYXNzd29yZCIsImlwIjoidGhlcmVtb3RlYWRkcm9mdGhldXNlciIsIm1haWwiOiJ1c2VybWFpbEB1c2VybWFpbGRvbWFpbi50bGQiLCJhdXRoX3Rva2VuIjoieW91cmF1dGh0b2tlbm9mY2hvaWNlIn0=
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
19 }}}
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
20
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
21 Where the encoded content is this (example) JSON Array:
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
22
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
23 <code language="javascript">
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
24 {"username":"usernameofchoice","password":"theuserpassword","ip":"theremoteaddroftheuser","mail":"usermail@usermaildomain.tld","auth_token":"yourauthtokenofchoice"}
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
25 </code>
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
26
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
27 Your form implementation needs to pass *all* parameters, the auth_token is needed to prevent misuses, if the request is successfull the server will answer with status code 200 and with the body of the response containing the token which your web app can send via e-mail to the user to complete the registration.
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
28
345
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
29 Else, it will reply with the following http error codes:
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
30
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
31 * 400 - if there's an error syntax;
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
32 * 401 - whenever an username is already pending registration or the auth token supplied is invalid;
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
33 * 403 - whenever registration is forbidden (blacklist, filtered mail etc.);
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
34 * 406 - if the username supplied fails nodeprepping;
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
35 * 409 - if the user already exists, or an user is associated already with the supplied e-mail;
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
36 * 503 - whenever a request is throttled.
73b078aeaf84 Added description of the http error codes' meaning.
maranda3985@gmail.com
parents: 344
diff changeset
37
346
a058cd983c6b Added directions to where the URL path for registration verification is.
maranda3985@gmail.com
parents: 345
diff changeset
38 The verification URL path to direct the users to will be: */your-base-path-of-choice/verify/* - on your Prosody's http server.
a058cd983c6b Added directions to where the URL path for registration verification is.
maranda3985@gmail.com
parents: 345
diff changeset
39
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
40 The module for now stores a hash of the user's mail address to help slow down duplicated registrations.
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
41
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
42 It's strongly encouraged to have the web server communicate with the servlet via https.
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
43
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
44 = Usage =
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
45
347
eebd8417a2ad Updated as the whole module folder is supposed to be copied now.
maranda3985@gmail.com
parents: 346
diff changeset
46 Copy the module folder and all its contents (register_json) into your prosody modules' directory.
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
47 Add the module your vhost of choice modules_enabled.
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
48
404
37502ad2fcb8 Edited wiki page mod_register_json through web user interface.
maranda3985@gmail.com
parents: 347
diff changeset
49 Hint: pairing with mod_register_redirect is helpful, to allow server registrations only via your webform.
185
9aab3736b3ca Added hint.
maranda3985@gmail.com
parents: 184
diff changeset
50
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
51 Optional configuration directives:
229
9278544faffb correction to code block.
maranda@lightwitch.org
parents: 228
diff changeset
52 <code language="lua">
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
53 reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account)
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
54 reg_servlet_secure = true -- Have the plugin only process requests on https (default is true)
187
4a6c1e35788c Fixed an error.
maranda3985@gmail.com
parents: 186
diff changeset
55 reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address.
228
818b1135d3e3 corrected wording.
maranda@lightwitch.org
parents: 191
diff changeset
56 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.
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
57 reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling.
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
58 reg_servlet_filtered_mails = { ".*banneddomain.tld", ".*deamailprovider.tld" } -- allows filtering of mail addresses via Lua patterns.
229
9278544faffb correction to code block.
maranda@lightwitch.org
parents: 228
diff changeset
59 </code>
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
60
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
61 = Compatibility =
184
ad1b7e71c32e Created wiki page through web user interface.
maranda3985@gmail.com
parents:
diff changeset
62
344
980a177b8a19 editing the wiki to reflect changes
maranda3985@gmail.com
parents: 278
diff changeset
63 * 0.9