# HG changeset patch # User Peter Sanchez # Date 1599678848 25200 # Wed Sep 09 12:14:08 2020 -0700 # Node ID 9cd87dc6deb24139f463af91521b5ca9a0c621fa # Parent 56af72bb9fb4ad83ed9239338e496b4821eeeef0 Updating README diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,15 +1,38 @@ + nlotp [![nlshield](https://img.shields.io/badge/100%25-Netlandish-blue.svg?style=square-flat)](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 () + +[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 @@ ] ``` -* 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 @@ ```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_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 @@ ``` ### `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 @@ #### 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 @@ #### 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 @@ ### `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 @@ ### `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. (). 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 .