Metadata-Version: 1.1
Name: django-iitg-auth
Version: 0.0.4
Summary: ``django-iitg-auth`` is a reusable Django application which provides a custom authencation backend for authenticating with IIT Guwahati webmail servers, a login form and a utility view.
Home-page: https://github.com/narenchoudhary/django-iitg-auth
Author: Narendra Choudhary
Author-email: narendralegha.mail@gmail.com
License: BSD 3-Clause
Description: django-iitg-auth
        ================
        
        .. image:: https://img.shields.io/pypi/v/django-iitg-auth.svg?style=plastic
            :target: https://pypi.python.org/pypi/django-iitg-auth
        
        .. image:: https://travis-ci.org/narenchoudhary/django-iitg-auth.svg?branch=master
            :target: https://travis-ci.org/narenchoudhary/django-iitg-auth
        
        .. image:: https://codecov.io/gh/narenchoudhary/django-iitg-auth/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/narenchoudhary/django-iitg-auth
        
        
        ``django-iitg-auth`` is a reusable Django application which provides
        a custom authencation backend for authenticating with IIT Guwahati webmail servers,
        a login form and a utility view.
        
        Installation
        ============
        
        ``django-iitg-auth`` can be installed using following pip command.
        
        .. code-block:: python
        
            pip install django-iitg-auth
        
        
        Usage: Authentication Backend
        =============================
        
        Add ``'iitgauth'`` to INSTALLED_APPS settings of the project.
        
        .. code-block:: python
        
            INSTALLED_APPS = [
                'django.contrib.admin',
                'django.contrib.auth',
                ...
                ...
                'iitgauth',
            ]
        
        Add ``'iitgauth.auth.WebMailAuthenticationBackend'`` to ``AUTHENTICATION_BACKENDS`` in settings.py.
        
        .. code-block:: python
        
            AUTHENTICATION_BACKENDS = [
                'django.contrib.auth.backends.ModelBackend',
                'iitgauth.auth.WebMailAuthenticationBackend',
            ]
        
        
        This is all the configuration required to use the webmail authentication backend.
        
        
        Note that ``authenticate`` method of the backend requires following credentials:
            * username
            * password
            * login server
            * port (default is set to 995)
        
        Following snippet shows how webmail authentication can be done in a custom view.
        
        .. code-block:: python
        
            from django.contrib.auth import authenticate
            from django.views.generic import View
        
            class LoginView(View):
        
                def get(self, request):
                    # get request handling logic
                    #
        
                def post(self, request):
                    form = LoginForm(request.POST)
                    if form.is_valid():
                        username = form.cleaned_data('username')
                        password = form.cleaned_data('password')
                        login_server = form.cleaned_data('login_server')
        
                        # open a socket to login server and query validity of credentials
                        user = auth.authenticate(username=username, password=password,
                                    login_server=login_server, port=995)
                        #
                        # rest of authentication logic
                        #
                   else:
                       # invalid form hadling
        
        
        Usage: ``WebmailLoginForm`` and ``WebmailLoginView``
        ====================================================
        A ready-to-use form (``WebmailLoginForm``) and a class based view (``WebmailLoginView``) are also available.
        Using this form and view is not necessary. You can write your own custom login form and view to use with
        webmail authentication backend as explained above.
        
        This form works exactly similar to Django's built-in AuthenticationForm_.
        Only difference is ``WebmailLoginForm`` has one extra field, .i.e. Login Server field.
        
        ``WebmailLoginForm`` has 3 fields:
            * username
            * password
            * login_server
        
        .. _AuthenticationForm: https://docs.djangoproject.com/en/1.10/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm
        
        
        ``WebmailLoginView`` is a FormView_ which renders ``WebmailLoginForm`` on GET and redirects to ``success_url`` on successful authentication.
        
        .. _FormView: https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-editing/#formview
        
        
        Demo
        ====
        
        **Note:** There is a working demo project available under **example** directory.
        
        .. image:: demo.gif
           :height: 180 px
           :width: 320 px
           :alt: demo
           :align: left
        
Keywords: django library development authentication
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
