Permalink
Browse files

Move docs out of README into real documentation.

  • Loading branch information...
clokep committed Dec 13, 2017
1 parent fe8c9b1 commit 40a48ff41e75438be45604b69081e9735b1a441b
Showing with 371 additions and 138 deletions.
  1. +3 −0 .gitignore
  2. +1 −1 CHANGELOG.rst
  3. +9 −137 README.rst
  4. +24 −0 docs/Makefile
  5. +25 −0 docs/advanced.rst
  6. +1 −0 docs/changelog.rst
  7. +146 −0 docs/conf.py
  8. +17 −0 docs/index.rst
  9. +104 −0 docs/installation.rst
  10. +36 −0 docs/make.bat
  11. +5 −0 requirements.txt
View
@@ -13,3 +13,6 @@ django_allauth_2fa.egg-info/
# Testing
.coverage
.tox
# Docs
_build
View
@@ -13,7 +13,7 @@ Changelog
* Add base middleware to ensure particular users (e.g. superusers) have 2FA
enabled.
* Drop official support for Django 1.9 and 1.10, they're
[no longer supported](https://www.djangoproject.com/download/#supported-versions)
`no longer supported <https://www.djangoproject.com/download/#supported-versions>`_
by the Django project.
0.4.4 March 24, 2017
View
@@ -1,15 +1,18 @@
django-allauth-2fa
==================
Welcome to django-allauth-2fa!
==============================
.. image:: https://travis-ci.org/percipient/django-allauth-2fa.svg?branch=master
:target: https://travis-ci.org/percipient/django-allauth-2fa
.. image:: https://coveralls.io/repos/github/percipient/django-allauth-2fa/badge.svg?branch=master
:target: https://coveralls.io/github/percipient/django-allauth-2fa?branch=master
django-allauth-2fa adds `two-factor authentication`_ to `django-allauth`_, a set
of `Django`_ applications which help with authentication, registration, and
other account management tasks.
django-allauth-2fa adds `two-factor authentication`_ to `django-allauth`_.
django-allauth is a set of `Django`_ applications which help with
authentication, registration, and other account management tasks.
Source code
http://github.com/percipient/django-allauth-2fa
.. _two-factor authentication: https://en.wikipedia.org/wiki/Multi-factor_authentication
.. _django-allauth: https://github.com/pennersr/django-allauth
@@ -22,140 +25,9 @@ Features
* Supports Authenticator apps via a QR code when enabling 2FA.
* Supports single-use back-up codes.
Installation
Contributing
------------
Install `django-allauth-2fa` with pip (note that this will install Django,
django-allauth, django-otp, qrcode and all of their requirements):
.. _django-otp: https://bitbucket.org/psagers/django-otp/
.. _qrcode: https://github.com/lincolnloop/python-qrcode
.. code-block:: bash
pip install django-allauth-2fa
After all the pre-requisities are installed, django-allauth and django-otp must
be configured in your Django settings file. (Please check the
`django-allauth documentation`_ and `django-otp documentation`_ for more
in-depth steps on their configuration.)
.. _django-allauth documentation: https://django-allauth.readthedocs.io/en/latest/installation.html
.. _django-otp documentation: http://pythonhosted.org/django-otp/overview.html#installation
.. code-block:: python
INSTALLED_APPS = (
# Required by allauth.
'django.contrib.sites',
# Configure Django auth package.
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
# Enable allauth.
'allauth',
'allauth.account',
# Configure the django-otp package.
'django_otp',
'django_otp.plugins.otp_totp',
'django_otp.plugins.otp_static',
# Enable two-factor auth.
'allauth_2fa',
)
MIDDLEWARE_CLASSES = (
# Configure Django auth package.
'django.contrib.auth.middleware.AuthenticationMiddleware',
# Configure the django-otp package. Note this must be after the
# AuthenticationMiddleware.
'django_otp.middleware.OTPMiddleware',
# Reset login flow middleware. If this middleware is included, the login
# flow is reset if another page is loaded between login and successfully
# entering two-factor credentials.
'allauth_2fa.middleware.AllauthTwoFactorMiddleware',
)
# Set the allauth adapter to be the 2FA adapter.
ACCOUNT_ADAPTER = 'allauth_2fa.adapter.OTPAdapter'
# Configure your default site. See
# https://docs.djangoproject.com/en/dev/ref/settings/#sites.
SITE_ID = 1
After the above is configure, you must run migrations.
.. code-block:: bash
python manage.py migrate
Finally, you must include the django-allauth-2fa URLs:
.. code-block:: python
from django.conf.urls import include, url
urlpatterns = [
# Include the allauth and 2FA urls from their respective packages.
url(r'^', include('allauth_2fa.urls')),
url(r'^', include('allauth.urls')),
]
.. warning::
Any login view that is *not* provided by django-allauth will bypass the
allauth workflow (including two-factor authentication). The Django admin
site includes an additional login view (usually available at
``/admin/login``).
The easiest way to fix this is to wrap it in ``login_required`` decorator
(the code only works if you use the standard admin site, if you have a
custom admin site you'll need to customize this more):
.. code-block:: python
from django.contrib import admin
from django.contrib.auth.decorators import login_required
# Ensure users go through the allauth workflow when logging into admin.
admin.site.login = login_required(admin.site.login)
# Run the standard admin set-up.
admin.autodiscover()
Advanced Configuration
----------------------
Forcing a User to Use 2FA
'''''''''''''''''''''''''
A ``User`` can be forced to use 2FA based on any requirements (e.g. superusers
or being in a particular group). This is implemented by subclassing the
``allauth_2fa.middleware.BaseRequire2FAMiddleware`` and implementing the
``require_2fa`` method on it. This middleware needs to be added to your
``MIDDLEWARE_CLASSES`` setting.
For example, to require a user to be a superuser:
.. code-block:: python
from allauth_2fa.middleware import BaseRequire2FAMiddleware
class RequireSuperuser2FAMiddleware(BaseRequire2FAMiddleware):
def require_2fa(self, request):
# Superusers are require to have 2FA.
return request.user.is_superuser
If the user doesn't have 2FA enabled they will be redirected to the 2FA
configuration page and will not be allowed to access (most) other pages.
Contribute
----------
django-allauth-2fa was initially created by
`Víðir Valberg Guðmundsson (@valberg)`_, and is currently maintained by
`Percipient Networks`_. Please feel free to contribute if you find
View
@@ -0,0 +1,24 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = django-allauth-2fa
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
livehtml:
sphinx-autobuild --open-browser --watch=../allauth_2fa --watch=. "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
echo @$(SPHINXBUILD) $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
View
@@ -0,0 +1,25 @@
Advanced Configuration
----------------------
Forcing a User to Use 2FA
'''''''''''''''''''''''''
A ``User`` can be forced to use 2FA based on any requirements (e.g. superusers
or being in a particular group). This is implemented by subclassing the
``allauth_2fa.middleware.BaseRequire2FAMiddleware`` and implementing the
``require_2fa`` method on it. This middleware needs to be added to your
``MIDDLEWARE_CLASSES`` setting.
For example, to require a user to be a superuser:
.. code-block:: python
from allauth_2fa.middleware import BaseRequire2FAMiddleware
class RequireSuperuser2FAMiddleware(BaseRequire2FAMiddleware):
def require_2fa(self, request):
# Superusers are require to have 2FA.
return request.user.is_superuser
If the user doesn't have 2FA enabled they will be redirected to the 2FA
configuration page and will not be allowed to access (most) other pages.
View
@@ -0,0 +1 @@
.. include:: ../CHANGELOG.rst
View
@@ -0,0 +1,146 @@
# -*- coding: utf-8 -*-
#
# django-allauth-2fa documentation build configuration file, created by
# sphinx-quickstart on Wed Mar 1 19:48:33 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'django-allauth-2fa'
copyright = u'2017, Víðir Valberg Guðmundsson, Percipient Networks'
author = u'Víðir Valberg Guðmundsson, Percipient Networks'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'0.4.3'
# The full version, including alpha/beta/rc tags.
release = u'0.4.3'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
html_theme = "sphinx_rtd_theme"
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'django-allauth-2fadoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'django-allauth-2fa.tex', u'django-allauth-2fa Documentation',
u'Víðir Valberg Guðmundsson, Percipient Networks', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'django-allauth-2fa', u'django-allauth-2fa Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'django-allauth-2fa', u'django-allauth-2fa Documentation',
author, 'django-allauth-2fa', 'One line description of project.',
'Miscellaneous'),
]
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
View
@@ -0,0 +1,17 @@
.. include:: ../README.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
installation
advanced
changelog
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Oops, something went wrong.

0 comments on commit 40a48ff

Please sign in to comment.