.. coding: utf-8

Configuration
`````````````

This guide assumes you already have a `Django project`_ and that all your applications use the recommended Django
methods for enforcing authentication, such as the |lr|_ decorator.

It also assumes that you have already created your OneAll site named ``mysite``, with public and private keys, and that
you have already used the `OneAll control panel`_ to set up at least one initial social network for login.

``settings.py``
^^^^^^^^^^^^^^^

First, add ``django_oneall`` to ``INSTALLED_APPS``, make sure you have ``django.contrib.auth`` before it::

    INSTALLED_APPS = (
        'django.contrib.auth',
        'django_oneall',
        # (…)
    )

Second, add the Django authentication backends::

    AUTHENTICATION_BACKENDS = (
        'django_oneall.auth.OneAllAuthBackend',
        'django_oneall.auth.EmailTokenAuthBackend',  # Optional
    )

If you plan to use E-mail Token authentication, you must also `configure your e-mail backend`_.
Here's a good development setting::

    EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Third, add the OneAll settings. Here's a minimal set-up::

    ONEALL = {
        'credentials': {
            'site_name': 'mysite',
            'public_key': '2d27cffd-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
            'private_key': '84d94998-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
        },
    }

Here's a different, more detailed alternative to the third step::

    ONEALL = {
        'credentials': {
            'site_name': 'mysite',
            'public_key': '2d27cffd-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
            'private_key': '84d94998-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
        },
        'login_widget': {
            'providers': ['amazon', 'blogger', 'disqus', 'draugiem', 'facebook',
                          'foursquare', 'github', 'google', 'instagram', 'linkedin',
                          'livejournal', 'mailru', 'odnoklassniki', 'openid',
                          'paypal', 'reddit', 'skyrock', 'stackexchange', 'steam',
                          'twitch', 'twitter', 'vimeo', 'vkontakte', 'windowslive',
                          'wordpress', 'yahoo', 'youtube'],
            'grid_sizes': [7, 5],
            # Any setting allowed in the login widget assistant can be put here.
        },
        'store_user_info': False,
        'max_username_length': 30,
        'email_token_expiration_hours': 3,
    }

In the above example, the ``store_user_info`` feature is set to ``False`` (defaults to ``True``).  This
setting provides your users with true anonymity, as none of the information provided by
oneall.com is saved or even cached.  Instead the user's oneall identification token is hashed
and stored as the username.

The example above also makes use of the ``max_username_length`` setting (defaults to ``30``).  This setting affects
all generated usernames, most prominently when ``store_user_info`` is ``False``.  The primary reason for this new
setting (introduced at django-oneall 1.3) is that Django 1.10 included a migration which altered the ``auth.User``
model's username field ``max_length`` from 30 to 150 chars.  This means if you were not storing user info with
``Django<1.10`` & ``django-oneall<1.3`` and upgraded to ``Django>=1.10`` & ``django-oneall<1.3``, your pre-existing
users **have beeen misidentified**.  If this is the case, you should verify your user table and evaluate whether the
best value for this is `30` or `150`.


Update Database
^^^^^^^^^^^^^^^

As with any Django app install::

    manage.py migrate

After that, if you're updating from 0.1.4 or older, the legacy table ``oneall_cache`` is ignored since 0.2
(September 2015). In order to import users from the old to the new table, you need to also run::

    manage.py legacyimport

``urls.py``
^^^^^^^^^^^
Add the following URL pattern to your ``urlpatterns`` in your global ``urls.py``::

    import django_oneall.urls

    url(r'^accounts/', include(django_oneall.urls)),

Using this Django App in ``/accounts/`` will work as a drop-in replacement to ``django.contrib.auth``.

However, if you're using ``django.contrib.admin``, it implements its own login screen, which conflicts with OneAll's.
You then need to **also** override its login screen like so::

    import django_oneall.views

    url(r'^admin/login', django_oneall.views.oa_login),
    url(r'^admin/', include(admin.site.urls)),

Super User
^^^^^^^^^^

The super user command is::

    python manage.py setsuperuser [user]

Where ``[user]`` can be either of:

#. OneAll Token (a UUID).
#. Django user Id (an integer; see your ``auth_user`` table for a list).
#. An e-mail address.

For OneAll Token or Django user Id, your user must already exist and they will be promoted.

For e-mail authentication, the user will be created if necessary and will be promoted regardless.
The console will display the e-mail login link to be manually pasted in a web browser.
Should your end user be unavailable to complete login, don't worry, they have already been made super-user.

Templates and Views
^^^^^^^^^^^^^^^^^^^

This is an optional step. You'll see that there are three views provided by this package, with two templates:

================= ========== =============
Suggested Route   View name  HTML Template
================= ========== =============
/accounts/login   oa_login   login.html
/accounts/logout  oa_logout  *(none)*
/accounts/profile oa_profile profile.html
================= ========== =============

The default ``login.html`` and ``profile.html`` are built to be simple and effective.
However, should you need any customization, it's recommended to copy these two files to your project's
``templates`` directory like below and modify them to suit your needs::

    myproj
    +- manage.py
    +- myproj
    |  +- settings.py
    |  +- urls.py
    |  +- wsgi.py
    +- templates
       +- oneall
          +- login.html
          +- profile.html

Should you create any further pages that implement OneAll widgets, include in their ``<head>``::

    {% load oneall %}
    {% oneall_header %}

The login widget itself can be included manually as instructed through the wizard_, or, if you're feeling lazy::

    {% oneall_social_login %}

You can also pass an optional argument (it must be the Django ``User`` object) if you want social linking instead::

    {% oneall_social_login current_user %}

.. _Django project: https://docs.djangoproject.com/en/1.8/intro/tutorial01/
.. |lr| replace:: ``login_required``
.. _lr: https://docs.djangoproject.com/en/1.8/topics/auth/default/#django.contrib.auth.decorators.login_required
.. _OneAll control panel: https://app.oneall.com/applications/
.. _configure your e-mail backend: https://docs.djangoproject.com/en/1.8/ref/settings/#email-backend
.. _wizard: https://app.oneall.com/applications/application/implementation/wizard/social-login/