README.md 4.24 KB
Newer Older
1
# Browser fingerprint authenticate
2
This package allows you to obtain and use a user browser fingerprint for your web application as an authenticator.
Artjom Löbsack's avatar
Artjom Löbsack committed
3

4 5 6 7 8 9 10 11 12 13 14 15 16
# In action
If you want to test this method by yourself, check our [demo site](https://bfa.pythonanywhere.com).

# Content
- [Install](#install)
- [Usage](#usage)
    - [Django](#django)
    - [Flask](#flask)
- [Salt](#also)
- [Dependences](#using)
- [Python versions](#supported-python)
- [License](#license)

17
# Install
Artjom Löbsack's avatar
Artjom Löbsack committed
18 19
You can install package by:

20
`pip install bfa`
Artjom Löbsack's avatar
Artjom Löbsack committed
21

22 23 24 25
# Usage
At the moment, django and flask support is provided, in the future it is planned to add other frameworks.

## Django
26
Add `'bfa'` to your list of `INSTALLED_APPS` in _settings.py_:
27 28
```python
INSTALLED_APPS = [
29
    ...
30 31 32 33
    'bfa'
]
```

34
- You can get user fingerprint by:
35

36
    `bfa.fingerprint.get(request)`
37

38
- In template paste inside `<form></form>`:
39

40
    `{% load bfa %}{% fingerprint_input %}`
41

42
**For example:**
Artjom Löbsack's avatar
Artjom Löbsack committed
43

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
_login.html_
```html
...
<form method="post">
    {% csrf_token %}
    
    <input name="username">
    
    {% load bfa %}
    {% fingerprint_input %}
    
    <button type="submit">Log in</button>
</form>
...
```
59

Artjom Löbsack's avatar
Artjom Löbsack committed
60 61
_views.py_
```python
62 63 64 65 66 67 68
import bfa
from django.http import HttpResponse
from django.shortcuts import render

...


Artjom Löbsack's avatar
Artjom Löbsack committed
69 70
def login(request):
    if request.method == 'POST':
71
        # Getting a username
72
        username = request.POST.get('username')
73 74
        
        # Getting a fingerprint
75 76
        try:
            fp = bfa.fingerprint.get(request)
77
        except (ConnectionError, ValueError):
78
            return HttpResponse("Can't get fingerprint")
79 80 81
        
        # Here is the part where you process the 
        # username and fingerprint, according to the database
82
        ...
83

84
        return HttpResponse("You're logged in")
85 86 87 88

    return render(request, 'login.html')


89
...
90
```
91 92 93 94 95 96 97 98 99 100 101 102

# Flask
Add bfa context processor to your _app.py_:
```python
...
import bfa
from flask import Flask

app = Flask(__name__)


@app.context_processor
Artjom Löbsack's avatar
Artjom Löbsack committed
103 104
# Don't change name of this function
def bfa_flask():
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
    return bfa.templatetags.bfa.fingerprint_input()


...
```

- You can get user fingerprint by:

    `bfa.fingerprint.get(request)`

- In template paste inside `<form></form>`:

    `{{ fingerprint_input }}`

**For example:**

_login.html_
```html
...
<form method="post">
    <input name="username">

    {{ fingerprint_input }}
    
    <button type="submit">Log in</button>
</form>
...
```

_app.py_
```python
import bfa
from flask import Flask, request

app = Flask(__name__)

...


@app.route('/login/', methods=['POST', 'GET'])
def login():
    if request.method == 'POST':
        # Getting a username
        username = request.form['username']

        # Getting a fingerprint
        try:
            fp = bfa.fingerprint.get(request)
        except (ConnectionError, ValueError):
            return "Can't get fingerprint"
        
        # Here is the part where you process the 
        # username and fingerprint, according to the database
        ...

        return "You're logged in"

    else:
        return "Login page"


...
```

169
# Also
170
You can salt fingerprints by:
171 172 173

`bfa.fingerprint.get(request, use_salt=True)`

174
**For example:**
175 176 177

_views.py_
```python
178 179 180 181 182 183 184
import bfa
from django.http import HttpResponse
from django.shortcuts import render

...


185 186
def login(request):
    if request.method == 'POST':
187
        # Getting a username
188
        username = request.POST.get('username')
189 190
        
        # Getting a fingerprint
191 192 193 194
        try:
            fp_data = bfa.fingerprint.get(request, use_salt=True)
        except (ConnectionError, ValueError):
            return HttpResponse("Can't get fingerprint")
195

196 197
        fp = fp_data['fp']
        salt = fp_data['salt']
198 199 200
        
        # Here is the part where you process the 
        # username, fingerprint and salt, according to the database
201
        ...
202
        
203
        return HttpResponse("You're logged in")
204 205
        
    return render(request, 'login.html')
206 207


208 209
...
```
210

211
# Using
212
This project uses:
213
- [Django](https://github.com/django/django "Python")
214
- [Werkzeug](https://github.com/pallets/werkzeug "Python")
215 216 217 218
- [FingerprintJS2](https://github.com/Valve/fingerprintjs2 "JS")
- [JS-SHA3](https://github.com/emn178/js-sha3 "JS")

# Supported python
219
BFA working on python >=3.5 only.
220

221 222
# License
This project is under Apache 2.0 license.