Browse Source

Finish README.md

master
Alfred 1 year ago
parent
commit
d10b25fd67
6 changed files with 92 additions and 8 deletions
  1. 84
    5
      README.md
  2. 2
    2
      config.py
  3. BIN
      imgs/no-data.png
  4. BIN
      imgs/with-data.png
  5. 0
    1
      tests/test_application.py
  6. 6
    0
      wsgi.py

+ 84
- 5
README.md View File

@@ -1,15 +1,89 @@
1 1
 # JaWTh
2 2
 
3
-JWT Authenticator coded in python using Flask. It publishes several end points to manage 
3
+JWT Authenticator coded in python 3 using Flask. It publishes several end points to manage 
4 4
 users and applications and the corresponding credentials.
5 5
 
6 6
 ## How it works?
7 7
 
8
+It stores applications and users. Applications have a name and a secret key for generating
9
+JWT. Users have a username, an encrypted password, and a timestamp of the last login between other 
10
+fields. Each user corresponds to an application.
11
+
12
+When a user makes a request of login in that application JaWTh compares the passwords,
13
+if the request is valid also signs a JWT with the username, the user id, and the timestamp.
14
+JaWTh returns this info as token to the client. Then the client will send this JWT
15
+in each request for making any action into the application. 
16
+
17
+When the application receives the JWT, decodes the token and will apply the required actions
18
+for the user indicated into the token.
19
+
20
+### Security concerns    
21
+
22
+  * The timestamp allows to expire tokens at application level.
23
+  * Passwords are stored encrypted (of course!).
24
+  * The secret key for signing tokens should only be known by the encoder and the decoder 
25
+    (JaWth and the application).
26
+  * To make changes into JaWTh you must know a password and its own secret key for JWT.
27
+  * It forces the HS256 algorithm. So clients are not allowed to set the signature 
28
+    algorithm in the HTTP, with it they cannot set the signature to `alg=none`.
29
+
30
+### Possible improvements
31
+
32
+  * For banning users it could make requests to webhooks implemented into the application 
33
+    target.
34
+  * It could manage mailing for recovering passwords and confirm accounts. Also sign ups.
35
+  * It could be an application key for letting them to add and remove users.
36
+
8 37
 ## Using it
9 38
 
39
+Clients comunicate with JaWTh using HTTP requests to the different end points. It is 
40
+required to provide an ``auth`` request header with the value ``jwt <jwt>``. Below you 
41
+can find examples.
42
+
43
+To generate the JWT there are multiple libraries for the most popular programming languages. 
44
+[jwt.io](https://jwt.io/) offers a tool to do it directly on their website.
45
+
46
+The JSON to be encoded would be one that includes the ``JAWTH_KEY`` into the field 
47
+``password``. If the request requires to senddata the JSON should also include another field 
48
+with the field ``data``.
49
+
50
+Here is a generated JWT for a request that no requires to send data:
51
+
52
+![](./imgs/no-data.png)
53
+
54
+And here one that requires to send data:
55
+
56
+![](./imgs/with-data.png)
57
+
58
+### Configuring and launching
59
+
60
+To configure JaWTht there is a config file into the project root folder. It's not 
61
+recommended to change that but to create a new one. To specify the execution of JaWTh
62
+to use that one define a ``JAWTH_CONFIG`` environment variable with the path of the 
63
+new config file.
64
+
65
+Your config file should define the next variables:
66
+  * **DEBUG**: Set to False
67
+  * **SECRET_KEY**: The JaWTh secret key, the one to use to sign and decode those request
68
+  sent to JaWTh.
69
+  * **JAWTH_KEY**: The JaWTh password, the one to use on the JWT.
70
+  * **SQLALCHEMY_DATABASE_URI**: The database uri.
71
+  
72
+Two examples of database uri are:
73
+  * Sqlite: ```sqlite:////tmp/database.db```
74
+  * PostgreSQL: ```postgresql://postgres:mysecretpassword@127.0.0.1:5432/jawth```
75
+
76
+
77
+To use PostgreSQL remember to create a database before launching for first time JaWTh. 
78
+For example: ``create database jawth;``
79
+
80
+To execute a JaWTh development version launch the `run.py` script.
81
+
82
+To run it using Gunicorn use the `wsgi.py` script: `gunicorn --bind 0.0.0.0:8000 wsgi:app`
83
+
10 84
 ### Examples
11 85
 
12
-Here is a list of examples of how to use the endpoints. 
86
+Here is a list of examples of how to use some of the end points.
13 87
 
14 88
 #### List applications [Admin]
15 89
 
@@ -78,7 +152,7 @@ curl --request POST \
78 152
 }'
79 153
 ```
80 154
 
81
-#### Change 'user1' password
155
+#### Change 'user1' password [User]
82 156
 
83 157
 Here we need a proper token. This one uses the time of last login: `2018-09-12 12:44:51.715047`
84 158
 
@@ -91,6 +165,11 @@ curl --request POST \
91 165
 	"password": "pass1234again",
92 166
 	"repeated_password": "pass1234again"
93 167
 }'
94
-``` 
168
+```
169
+
170
+#### Other end points
171
+
172
+  * CRUD on all users: POST, GET, PATCH, DELETE ─ `/users[/userid]`
173
+  * CRUD on all applications: POST, GET, PATCH, DELETE ─ `/application[/appname]`
174
+
95 175
 
96
-#### Other end points

+ 2
- 2
config.py View File

@@ -12,8 +12,8 @@ SECRET_KEY = 'JAWTHSECRETKEY'
12 12
 JAWTH_KEY = 'JAWTHPASSWORD'
13 13
 
14 14
 # Connect to the database
15
-# SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'database.db')
16
-SQLALCHEMY_DATABASE_URI = 'postgresql://postgres:mysecretpassword@127.0.0.1:5432/jawth'
15
+SQLALCHEMY_DATABASE_URI = 'sqlite:///' + os.path.join(basedir, 'database.db')
16
+# SQLALCHEMY_DATABASE_URI = 'postgresql://postgres:mysecretpassword@127.0.0.1:5432/jawth'
17 17
 
18 18
 ENV = 'development'
19 19
 SQLALCHEMY_TRACK_MODIFICATIONS = False

BIN
imgs/no-data.png View File


BIN
imgs/with-data.png View File


+ 0
- 1
tests/test_application.py View File

@@ -229,7 +229,6 @@ class JaWThTestCase(unittest.TestCase):
229 229
         token_2 = res.get_json()['token']
230 230
         assert token_1 != token_2
231 231
 
232
-
233 232
     def test_login_wrong(self):
234 233
         user = self.create_test_user(encode_password=True)
235 234
         res = self.app.post('/{}/login'.format(user.app.name),

+ 6
- 0
wsgi.py View File

@@ -0,0 +1,6 @@
1
+#!/usr/bin/env python
2
+# -*- coding: utf-8 -*-
3
+
4
+from app import app, initialize_app
5
+
6
+initialize_app()

Loading…
Cancel
Save