Mercurial > prosody-modules

comparison mod_register_json/README.markdown @ 1803:4d73a1a6ba68

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Convert all wiki pages to Markdown
author Kim Alvefur <zash@zash.se>
date Fri, 28 Aug 2015 18:03:58 +0200
parents
children ea6b5321db50
comparison
equal deleted inserted replaced
1802:0ab737feada6 1803:4d73a1a6ba68
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
27 {"username":"usernameofchoice","password":"theuserpassword","ip":"theremoteaddroftheuser","mail":"usermail@usermaildomain.tld","auth\_token":"yourauthtokenofchoice"}\</code\>
28
29 Your form implementation needs to pass **all** parameters, the
30 auth\_token is needed to prevent misuses, if the request is successfull
31 the server will answer with status code 200 and with the body of the
32 response containing the token which your web app can send via e-mail to
33 the user to complete the registration.
34
35 Else, it will reply with the following http error codes:
36
37 - 400 - if there's an error syntax;
38 - 401 - whenever an username is already pending registration or the
39 auth token supplied is invalid;
40 - 403 - whenever registration is forbidden (blacklist, filtered mail
41 etc.);
42 - 406 - if the username supplied fails nodeprepping;
43 - 409 - if the user already exists, or an user is associated already
44 with the supplied e-mail;
45 - 503 - whenever a request is throttled.
46
47 The verification URL path to direct the users to will be:
48 **/your-base-path-of-choice/verify/** - on your Prosody's http server.
49
50 The module for now stores a hash of the user's mail address to help slow
51 down duplicated registrations.
52
53 It's strongly encouraged to have the web server communicate with the
54 servlet via https.
55
56 Usage
57 -----
58
59 Copy the module folder and all its contents (register\_json) into your
60 prosody modules' directory.Add the module your vhost of choice
61 modules\_enabled.
62
63 Hint: pairing with mod\_register\_redirect is helpful, to allow server
64 registrations only via your webform.
65
66 Optional configuration directives:
67
68 reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account)
69 reg_servlet_secure = true -- Have the plugin only process requests on https (default is true)
70 reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address.
71 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.
72 reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling.
73 reg_servlet_filtered_mails = { ".*banneddomain.tld", ".*deamailprovider.tld" } -- allows filtering of mail addresses via Lua patterns.
74
75 Compatibility
76 -------------
77
78 0.9