From 85f59dc8b3e4d36104e92f3efa0361be6aef14b6 Mon Sep 17 00:00:00 2001 From: Ruben Grill Date: Sun, 2 Sep 2018 12:49:05 +0200 Subject: [PATCH] docs: Update docs --- docs/index.rst | 3 ++- docs/rest.rst | 43 +++++++++++++++++++++++++++++++++++ docs/settings.rst | 34 +++------------------------- docs/usage.rst | 57 +++++++++++++++++++++++++---------------------- 4 files changed, 78 insertions(+), 59 deletions(-) create mode 100644 docs/rest.rst diff --git a/docs/index.rst b/docs/index.rst index 38fc993..e682e3e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,8 @@ Run this command to install django-nopassword:: pip install django-nopassword Requirements: -Django >= 1.4 (1.5 custom user is supported) +Django >= 1.11 (custom user is supported) .. include:: usage.rst +.. include:: rest.rst .. include:: settings.rst diff --git a/docs/rest.rst b/docs/rest.rst new file mode 100644 index 0000000..44c010e --- /dev/null +++ b/docs/rest.rst @@ -0,0 +1,43 @@ +REST API +-------- +To use the REST API, *djangorestframework* must be installed:: + + pip install djangorestframework + +Add rest framework to installed apps:: + + INSTALLED_APPS = ( + ... + 'rest_framework', + 'rest_framework.authtoken', + 'nopassword', + ... + ) + +Add *TokenAuthentication* to default authentication classes:: + + REST_FRAMEWORK = { + 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'rest_framework.authentication.TokenAuthentication', + ) + } + +Add urls to your *urls.py*:: + + urlpatterns = patterns('', + ... + url(r'^api/accounts/', include('nopassword.rest.urls')), + ... + ) + +You will have the following endpoints available: + +- `/api/accounts/login/` (POST) + - username + - next (optional, will be returned in ``/api/accounts/login/code/`` to be handled by the frontend) + - Sends a login code to the user +- `/api/accounts/login/code/` (POST) + - code + - Returns ``key`` (authentication token) and ``next`` (provided by ``/api/accounts/login/``) +- `/api/accounts/logout/` (POST) + - Performs logout diff --git a/docs/settings.rst b/docs/settings.rst index 05b529f..81f6df9 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -12,36 +12,17 @@ django-nopassword settings Defines how long a login code is valid in seconds. -.. attribute:: NOPASSWORD_NAMESPACE - - Default: ``'nopassword'`` - - Defines the namespace for the urls, this must match the namespace of the include of - nopassword.urls. - -.. attribute:: NOPASSWORD_HIDE_USERNAME - - Default: ``False`` - - If set to True, the login url will not contain the username. - -.. attribute:: NOPASSWORD_LOGIN_EMAIL_SUBJECT - - Default: ``_('Login code')`` - - Sets Email Subject for Login Emails. - .. attribute:: NOPASSWORD_HASH_ALGORITHM Default: ``'sha256'`` Set the algorithm for used in logincode generation. Possible values are those who are supported in hashlib. The value should be set as the name of the attribute in hashlib. Example `hashlib.sha256()` would be `NOPASSWORD_HASH_ALGORITHM = 'sha256'. -.. attribute:: NOPASSWORD_POST_REDIRECT +.. attribute:: NOPASSWORD_LOGIN_ON_GET - Default: ``True`` + Default: ``False`` - By default, the login code url requires a POST request to authenticate the user. A GET request renders ``registration/login_submit.html``, which contains some Javascript that automatically performs the POST on page load. To authenticate directly inside the initial GET request instead, set this to ``False``. + By default, the login code url requires a POST request to authenticate the user. A GET request renders a form that must be submitted by the user to perform authentication. To authenticate directly inside the initial GET request instead, set this to ``True``. .. attribute:: NOPASSWORD_CODE_LENGTH @@ -66,15 +47,6 @@ django-nopassword settings Django settings used in django-nopassword +++++++++++++++++++++++++++++++++++++++++ -.. attribute:: SERVER_URL - - Default: ``'example.com'`` - - By default, ``nopassword.views.login`` passes the result of ``result.get_host()`` to - ``LoginCode.send_login_code`` to build the login URL. If you write your own view - and/or want to avoid this behavior by not passing a value for host, the - ``SERVER_URL`` setting will be used instead. - .. attribute:: DEFAULT_FROM_EMAIL Default: ``'root@example.com'`` diff --git a/docs/usage.rst b/docs/usage.rst index c0b1b3a..f628d56 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -6,9 +6,15 @@ Add the app to installed apps:: 'nopassword', ) -Set the authentication backend to *EmailBackend*:: +Add the authentication backend *EmailBackend*:: - AUTHENTICATION_BACKENDS = ( 'nopassword.backends.email.EmailBackend', ) + AUTHENTICATION_BACKENDS = ( + # Needed to login by username in Django admin, regardless of `nopassword` + 'django.contrib.auth.backends.ModelBackend', + + # Send login codes via email + 'nopassword.backends.email.EmailBackend', + ) Add urls to your *urls.py*:: @@ -16,12 +22,6 @@ Add urls to your *urls.py*:: url(r'^accounts/', include('nopassword.urls')), ) -Verify users -~~~~~~~~~~~~ -If it is necessary to verify that users still are active in another system. Override -*verify_user(user)* to implement your check. In *NoPasswordBackend* that method checks -whether the user is active in the django app. - Backends ++++++++ There are several predefined backends. Usage of those backends are listed below. @@ -30,33 +30,36 @@ There are several predefined backends. Usage of those backends are listed below. .. class:: EmailBackend Delivers the code by email. It uses the django send email functionality to send -the emails. It will attach both HTML and plain-text versions of the email. +the emails. + +Override the following templates to customize emails: + +- ``registration/login_email.txt`` - Plain text message +- ``registration/login_email.html`` - HTML message (note that no default html message is attached) +- ``registration/login_subject.txt`` - Subject .. currentmodule:: nopassword.backends.sms .. class:: TwilioBackend Delivers the code by sms sent through the twilio service. +Override the following template to customize messages: + +- ``registration/login_sms.txt`` - SMS message + Custom backends ~~~~~~~~~~~~~~~ In backends.py there is a *NoPasswordBackend*, from which it is possible to build custom backends. The *EmailBackend* described above inherits from -this backend. Creating your own backend is can be done by creating a subclass -of *NoPasswordBackend* and implementing *send_login_code*. A good example is -the *EmailBackend*:: - - class EmailBackend(NoPasswordBackend): - - def send_login_code(self, code, secure=False, host=None): - subject = getattr(settings, 'NOPASSWORD_LOGIN_EMAIL_SUBJECT', _('Login code')) - to_email = [code.user.email] - from_email = getattr(settings, 'DEFAULT_FROM_EMAIL', 'root@example.com') - - context = {'url': code.login_url(secure=secure, host=host), 'code': code} - text_content = render_to_string('registration/login_email.txt', context) - html_content = render_to_string('registration/login_email.html', context) - - msg = EmailMultiAlternatives(subject, text_content, from_email, to_email) - msg.attach_alternative(html_content, 'text/html') - msg.send() +this backend. Creating your own backend can be done by creating a subclass +of *NoPasswordBackend* and implementing *send_login_code*.:: + + class CustomBackend(NoPasswordBackend): + + def send_login_code(self, code, context, **kwargs): + """ + Use code.user to get contact information + Use context to render a custom template + Use kwargs in case you have a custom view that provides additional configuration + """