Getting Started¶

In this tutorial we will get aquainted with how to use bpauth. bpauth provides many utilities to use to manage authentication and user data. Reading the source can be a bit daunting so we’ll go through the most basic usage here.

First we will start by creating a Django application named “account”.

$ python manage.py startapp account

Within the account application we will create the user model for our site. On this model we can add whatever fields might be useful to our application. The User class will extend from bpauth’s UserBase base model class.

Lets edit the models.py:

from django.db import models
from newauth.api import UserBase

class MyUser(UserBase):
    email = models.EmailField('Email Address')
    profile = models.TextField('Profile Bio', blank=True, null=True)
    avatar = models.ImageField('Avatar', upload_to='profileimg/', blank=True, null=True)

Here we have a basic user class for our application. All of the fields we want can be attached directly on the user object. Next we’ll want to make an anonymous user class that has the same fields as our user class:

from django.db import models
from newauth.api import AnonymousUserBase

class MyAnonymousUser(AnonymousUserBase):
    email = None
    profile = None
    avatar = None

Now let’s write a simple view.

from django.views.generic.simple import direct_to_template

from account.models import User

def my_profile(request):
    return direct_to_template(request, 'account/my_profile.html', {
        'avatar': request.auth_user.avatar,
        'profile': request.auth_user.profile,
    })

You see here we can access all of the fields pertaining to the user’s profile directly on the user object. This is very convenient as you do not have to use ‘get_profile()’ to get access to added fields for your user as you have to do with Django’s contrib.auth application.

The UserBase model defines a number of methods on it to allow third party applications to interact with your model. Because third party applications cannot assume you have any fields on your model besides the ‘pk’ field, third party applications need to interact with your MyUser model via these overridable methods.

Here we override the get_display_name() method to use the first part of the user’s email address as their display name. By default the UserBase class simply returns the user’s primary key.

class MyUser(UserBase):

    # ...

    def get_display_name(self):
        return self.email.split('@')[0]

The UserBase class also defines a get_real_name() method that can be used for internal, editing, and administrative functions where a real name would be more appropriate, such as invoicing etc.

In the next section we’ll discuss how to use newauth to create user models that use simple username/password authentication.

Basic Username/Password Authentication¶

newauth provides a basic submodule that provides some basic functionality for creating account applications with user models that use basic username/password authentication. It is a good example of how to use newauth to create your own user module.

The BasicUserBase model extends the UserBase model and adds a username and password field and implements password checking. Here we can create a MyUser model as we did before but with username/password functonality.

from django.db import models
from newauth.api import BasicUserBase

class MyUser(BasicUserBase):
    email = models.EmailField('Email Address')
    profile = models.TextField('Profile Bio', blank=True, null=True)
    avatar = models.ImageField('Avatar', upload_to='profileimg/', blank=True, null=True)

Now we can use the included BasicUserBackend and BasicAuthForm <newauth.forms.BasicAuthForm in combination with the login() view to authenticate our user.

Here we’ll set up the BasicUserBackend in settings.py:

NEWAUTH_BACKENDS = {
    'default': {
        'backend': 'newauth.backends.BasicUserBackend',
        'user': 'account.models.MyUser',
        'anon_user': 'account.models.MyAnonymousUser',
    }
}

The login() view uses the BasicAuthForm by default but we can tell it to use the BasicAuthForm explicitly.

from django.conf.urls import url
from django.conf import settings

from newauth.views import login
from newauth.forms import BasicAuthForm

urlpatterns = [
    url(r'^login$', login, name='newauth_login', kwargs={
        'authentication_form': BasicAuthForm,
    }),
]

We can also use the provided BasicUserAdmin to add functionality to Django’s admin. The BasicUserAdmin class implements creating new users and password change in much the same way as Django’s auth application. This makes it very easy to implement usable admin pages:

from django.contrib import admin
from beproud.django.auth.basic.admin import BasicUserAdmin

from account.models import MyUser

admin.site.register(MyUser, BasicUserAdmin)

In the next section we’ll discuss how to set up the login and logout urls.

Setting up the Login and Logout Views¶

In this section we’ll set up the provided login and logout views to allow for logging in using basic username and password authentication.

urlpatterns = [
    # ...
    url(r'^account/', include('newauth.urls')),
    # ...
]

urlpatterns = [
    # ...
    url(r'^login/$', 'newauth.views.login', name='newauth_login', kwargs={
        'authentication_form': MyLoginForm,
    }),
    # ...
]

Limiting access to logged-in users¶

from django.http import HttpResponseRedirect

def my_view(request):
    if not request.user.is_authenticated():
        return HttpResponseRedirect('/login/?next=%s' % request.path)
    # ...

from newauth.decorators import login_required

@login_required
def my_view(request):
    ...

from newauth.decorators import login_required

@login_required(login_url="/mylogin", redirect_field_name="next_url")
def my_view(request):
    ...

from newauth.decorators import login_required

@login_required(["default", "backend2"])
def my_view(request):
    ...

Tieing it all together¶

Now we’ll tie it all together by setting the appropriate settings in our settings.py.

As we mentioned in the Installation you’ll need to add newauth to your INSTALLED_APPS:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    #...
    'newauth',
    #...
)

and add the AuthMiddleware to your MIDDLEWARE_CLASSES

MIDDLEWARE_CLASSES = (
    #...
    'newauth.middleware.AuthMiddleware',
    #...
)

Here we will set up the NEWAUTH_BACKENDS so that we can authenticate and use our MyUser class that we set up earlier.

NEWAUTH_BACKENDS = {
    'default': {
        'backend': (
            'newauth.backend.BasicUserBackend',
        ),
        'user': 'account.models.MyUser',
        'anon_user': 'account.models.MyAnonymousUser',
    }
}

And that’s it! You should have a simple working example of how to use newauth. newauth allows a lot of customization so you can continue on and read some of the more advanced documentation or play some more with the example.

Good Luck!

newauth.admin¶

class newauth.admin.BasicUserCreationForm(*args, **kwargs)¶

A form that creates a user, with no privileges, from the given username and password.

class newauth.admin.PasswordChangeForm(user, *args, **kwargs)¶

A form used to change the password of a user in the admin interface.

save(commit=True)¶

Saves the new password.

newauth.api¶

Alex Gaynor will kill me

class newauth.api.UserBase(*args, **kwargs)¶

Base User class

Primary key can be defined in sub classes. This class makes no assumptions about the format of the primary key. Only a pk property (the primary key might be something other than id) and the methods implemented below can be assumed are present.

This class also makes no assumptions about underlying implementations like what fields are on the User object or the table name.

get_display_name()¶

Name for display. Usually a username or something similar. Usually used for public pages. This method should return a unicode object.

get_real_name()¶

The user’s real name or closest approximation. Usually used for private pages etc.

is_authenticated()¶

Returns whether a user is authenticated or not. The default is for this method to always return true for subclasses of UserBase and False for subclasses of AnonymousUserBase

class newauth.api.AnonymousUserBase¶

A simple anonymous user.

class newauth.api.BasicUserManager¶

A default manager that can be used with models that subclass BasicUserBase.

class newauth.api.BasicUserBase(*args, **kwargs)¶

A basic user that is authenticated with a username and password.

This class can be subclassed when using a simple username password auth system.

check_password(raw_password)¶

Returns a boolean of whether the raw_password was correct. Handles encryption formats behind the scenes.

set_password(raw_password)¶

Sets the password of the user. Alorithm

newauth.api.authenticate(_backend_name=None, **credentials)¶

Authenticate a user with using the available auth backends. If a _backend_name is provided require authentication via the backend with that name.

If the given credentials are valid, return a User object as provided by the backend.

newauth.api.login(request, user, backend_name=None)¶

Log the user in given the request object. This will save any data needed to auth the user (user id and backend name) using the auth session storage (not necessarily django sessions).

newauth.api.logout(request)¶

Logs the user out. This will clear the user’s login session data from the auth session storage.

newauth.backend¶

class newauth.backend.BasicUserBackend(backend_name)¶

A simple backend to authenticate any subclass of BasicUserBase.

newauth.decorators¶

newauth.decorators.login_required(backend_list=None, login_url=None, redirect_field_name='next')¶

Decorator for views that checks that the user is logged in, redirecting to the log-in page if necessary.

newauth.forms¶

class newauth.forms.BaseAuthForm(*args, **kwargs)¶

A base authentication form. Authentication forms can subclass this form and implement the get_credentials() method which will return a dictionary of credentials from self.cleaned_data that can be used with authenticate()

get_credentials()¶

Gets credentials as a dict object from self.cleaned_data

get_user()¶

Gets the cached user object for the user that logged in using this form.

class newauth.forms.BasicAuthForm(*args, **kwargs)¶

A basic authentication form that will authenticate a user using a username and password. Useful for subclasses of BasicUser.

newauth.middleware¶

class newauth.middleware.AuthMiddleware(get_response=None)¶

Middleware for getting the current user object and attaching it to the request.

newauth.models¶

newauth.models.get_user_model(model_name=None)¶

Used to get access to defined user models.

from newauth.models import User, get_user_model

OtherUser = get_user_model(‘other’)

class MyProfile(models.Model):

user = models.ForeignKey(User) other_user_type = models.ForeignKey(OtherUser)

newauth.views¶

newauth.views.login(request, *args, **kwargs)¶

Displays the login form and handles the login action.

newauth.views.logout(request, next_page=None, template_name='registration/logged_out.html', redirect_field_name='next')¶

Logs out the user and displays ‘You are logged out’ message.