@@ 1,15 1,38 @@
+ nlotp [](http://www.netlandish.com)
+----
+
+Django application to quickly provide you with TOTP with recovery codes right
+out of the box.
+
+**Version:** 0.1
+
+**Project Links:** [Issues][issues] - [Mailing List][pinbox] -
+[Contributing](#contributing)
+
+**Author:** Netlandish (<https://www.netlandish.com>)
+
+[issues]: https://todo.code.netlandish.com/~netlandish/django-nlotp
+[pinbox]: https://lists.code.netlandish.com/~netlandish/public-inbox
+
# Netlandish One-Time Password (Two-Factor Authentication)
-Netlandish OTP is a customization of [`django-otp`](https://github.com/django-otp/django-otp) app, using TOTP and Static plugins.
+Netlandish OTP is a customization of
+[`django-otp`](https://github.com/django-otp/django-otp) app, using TOTP and
+Static plugins.
-The user verification process is done by first checking a TOTP device match, if not found look for user maching Static device (backup codes).
+The user verification process is done by first checking a TOTP device match, if
+not found look for user matching Static device (backup codes).
-To enable one-time password, a TOTP verification code needs to be provided, by scanning the QR code or entering a key on an application like Google Authenticator.
-Once enabled, backup codes (Static device) are generated and Django user account password will be required for two actions: generating new backup codes and disabling 2FA.
+To enable one-time password, a TOTP verification code needs to be provided, by
+scanning the QR code or entering a key on an application like Google
+Authenticator. Once enabled, backup codes (Static device) are generated and
+Django user account password will be required for two actions: generating new
+backup codes and disabling 2FA.
## Installation
-* Add `django_otp`, `django_otp.plugins.otp_totp`, `django_otp.plugins.otp_static` and `nlotp` to `INSTALLED_APPS`. For example:
+* Add `django_otp`, `django_otp.plugins.otp_totp`,
+ `django_otp.plugins.otp_static` and `nlotp` to `INSTALLED_APPS`. For example:
```python
INSTALLED_APPS = [
@@ 27,7 50,9 @@ Once enabled, backup codes (Static devic
]
```
-* Add `nlotp.middleware.OTPCheckMiddleware` to `MIDDLEWARE`. It must be installed after `django.contrib.auth.middleware.AuthenticationMiddleware`. For example:
+* Add `nlotp.middleware.OTPCheckMiddleware` to `MIDDLEWARE`. It must be
+ installed after `django.contrib.auth.middleware.AuthenticationMiddleware`.
+ For example:
```python
MIDDLEWARE = [
@@ 48,17 73,24 @@ Once enabled, backup codes (Static devic
```python
urlpatterns = [
path('otp/', include('nlotp.urls', namespace='nlotp')),
- path('', include('yourapp.urls', namespace='yourapp')),
+ ...
]
```
## Settings
### `NLOTP_VERIFY_URL`
-Verify page url, user is redirected to this page after login if has 2FA enabled. Defaults to `nlotp:verify-otp` url.
+
+Verify page url, user is redirected to this page after login if has 2FA
+enabled. Defaults to `nlotp:verify-otp` url.
### `NLOTP_VERIFY_EXCLUDED_URLS`
-List of urls excluded from redirect to `NLOTP_VERIFY_URL` if logged in user has 2FA enabled but is not verified. Defaults to `(NLOTP_VERIFY_URL,)`. You should include your app login and logout urls in this list, for example include in your settings:
+
+List of urls excluded from redirect to `NLOTP_VERIFY_URL` if logged in user has
+2FA enabled but is not verified. Defaults to `(NLOTP_VERIFY_URL,)`. You should
+include your app login and logout urls in this list, for example include in
+your settings:
+
```python
NLOTP_VERIFY_EXCLUDED_URLS = (
reverse_lazy('login'),
@@ 68,16 100,27 @@ NLOTP_VERIFY_EXCLUDED_URLS = (
```
### `NLOTP_2FA_SETUP_REQUIRED`
-If 2FA setup is mandatory. Logged in user is forced to setup 2FA, redirected to `NLOTP_2FA_SETUP_URL`. Defaults to `False`.
+
+If 2FA setup is mandatory. Logged in user is forced to setup 2FA, redirected to
+`NLOTP_2FA_SETUP_URL`. Defaults to `False`.
### `NLOTP_2FA_SETUP_URL`
-2FA setup page url, where OTP setup is done (enable/disable and code generation). Defaults to `nlotp:two-factor-auth` url.
+
+2FA setup page url, where OTP setup is done (enable/disable and code
+generation). Defaults to `nlotp:two-factor-auth` url.
### `NLOTP_QR_CODE_URL`
-User TOTP device QR code generation url, returns a QR code SVG image. Defaults to `nlotp:qr-code` url.
+
+User TOTP device QR code generation url, returns a QR code SVG image. Defaults
+to `nlotp:qr-code` url.
### `NLOTP_SETUP_EXCLUDED_URLS`
-List of urls excluded from redirect to `NLOTP_2FA_SETUP_URL` when `NLOTP_2FA_SETUP_REQUIRED` is enabled and user has not setup 2FA. Defaults to `(NLOTP_2FA_SETUP_URL, NLOTP_QR_CODE_URL)`. You should include your app login and logout urls in this list, for example include in your settings:
+
+List of urls excluded from redirect to `NLOTP_2FA_SETUP_URL` when
+`NLOTP_2FA_SETUP_REQUIRED` is enabled and user has not setup 2FA. Defaults to
+`(NLOTP_2FA_SETUP_URL, NLOTP_QR_CODE_URL)`. You should include your app login
+and logout urls in this list, for example include in your settings:
+
```python
NLOTP_SETUP_EXCLUDED_URLS = (
reverse_lazy('login'),
@@ 88,18 131,26 @@ NLOTP_SETUP_EXCLUDED_URLS = (
```
### `OTP_TOTP_ISSUER`
-`django-otp` setting, this is how your app will be shown in the auth app (e.g. Google Authenticator). Defaults to `None`. It can be string or a callable. For example:
+
+`django-otp` setting, this is how your app will be shown in the auth app (e.g.
+Google Authenticator). Defaults to `None`. It can be string or a callable. For
+example:
+
```python
def totp_issuer(device):
return f'Your app name ({device.user.email})'
OTP_TOTP_ISSUER = totp_issuer
```
-Refer to [`django-otp` docs](https://django-otp-official.readthedocs.io/en/stable/overview.html#totp-settings) for more details.
+
+Refer to `django-otp` [documentation][djotpdocs] for more details.
+
+[djotpdocs]: https://django-otp-official.readthedocs.io/en/stable/overview.html#totp-settings
## Templates
-There are 2 basic templates provided with the app, that you should consider to override.
+There are 2 basic templates provided with the app, that you should consider to
+override.
### `nlotp/verify_otp.html`
@@ 107,7 158,8 @@ Verify page template.
#### Context variables
-`form`: customized version of `django-otp` `OTPTokenForm`; `otp_device` and `otp_token` fields should be included the template.
+- `form`: customized version of `django-otp` `OTPTokenForm`; `otp_device` and
+ `otp_token` fields should be included the template.
### `nlotp/two_factor_auth.html`
@@ 115,17 167,22 @@ 2FA setup page template.
#### Context variables
-`form`: user model form that includes `authentication_code` field (should be included in template if 2FA is disabled for user) and `password` (should be included in template if 2FA is enabled for user).
+- `form`: user model form that includes `authentication_code` field (should be
+ included in template if 2FA is disabled for user) and `password` (should be
+ included in template if 2FA is enabled for user).
-`totp_device`: user `TOTPDevice`, it could be `confirmed` (2FA enabled) or not (2FA disabled).
-
-`static_device`: user `StaticDevice`, it could be `confirmed` (2FA enabled) or not (2FA disabled).
+- `totp_device`: user `TOTPDevice`, it could be `confirmed` (2FA enabled) or
+ not (2FA disabled).
-`show_codes`: if backup codes (static device) should be shown, it's set to `True` after user enables 2FA or requests new backup codes.
+- `static_device`: user `StaticDevice`, it could be `confirmed` (2FA enabled)
+ or not (2FA disabled).
-`qr_code_url`: `NLOTP_QR_CODE_URL` url.
+- `show_codes`: if backup codes (static device) should be shown, it's set to
+ `True` after user enables 2FA or requests new backup codes.
-`setup_required`: `NLOTP_2FA_SETUP_REQUIRED` flag.
+- `qr_code_url`: `NLOTP_QR_CODE_URL` url.
+
+- `setup_required`: `NLOTP_2FA_SETUP_REQUIRED` flag.
## Utils
@@ 135,7 192,8 @@ Gets `user` `TOTPDevice` or creates a ne
### `utils.get_user_static_device`
-Gets `user` `StaticDevice` or creates a new one (not `confirmed`). Adds 10 new backup codes if created.
+Gets `user` `StaticDevice` or creates a new one (not `confirmed`). Adds 10 new
+backup codes if created.
### `utils.generate_user_static_tokens`
@@ 146,3 204,52 @@ Adds `count` (10 by default) backup code
### `mixins.TOTPDeviceMixin`
Simple mixin that inserts logged in user TOTP device in view context.
+
+# Contributing
+
+We accept patches submitted via `hg email` which is the `patchbomb` extension
+included with Mercurial.
+
+Please see our [contributing document][cdoc] for more information.
+
+The mailing list where you submit your patches is
+`~netlandish/public-inbox@lists.code.netlandish.com`. You can also view the
+archives on the web here:
+
+https://lists.code.netlandish.com/~netlandish/public-inbox
+
+To quickly setup your clone of `django-nlotp` to submit to the mailing
+list just edit your `.hg/hgrc` file and add the following:
+
+ [email]
+ to = ~netlandish/public-inbox@lists.code.netlandish.com
+
+ [patchbomb]
+ flagtemplate = "django-nlotp"
+
+ [diff]
+ git = 1
+
+We have more information on the topic here:
+
+- [Contributing][cdoc]
+- [Using email with Mercurial][hgemail]
+- [Mailing list etiquette][etiquette]
+
+[etiquette]: https://man.code.netlandish.com/lists/etiquette.md
+[hgemail]: https://man.code.netlandish.com/hg/email.md
+[cdoc]: https://man.code.netlandish.com/contributing.md
+
+# Copyright & Warranty
+
+All documentation, libraries, and sample code are Copyright 2020 Netlandish
+Inc. (<https://www.netlandish.com>). The library and sample code are
+made available to you under the terms of the BSD license which is contained in
+the included file, BSD-LICENSE.
+
+# Commercial Support
+
+This software, and lots of other software like it, has been built in
+support of many of Netlandish's own projects, and the projects of our
+clients. We would love to help you on your next project so get in touch
+by dropping us a note at <hello@netlandish.com>.