Authentication Forms and Templates

Built-in forms

If you don’t want to use the built-in views, but want the convenience of not having to write forms for this functionality, the authentication system provides several built-in forms located in django.contrib.auth.forms(Table 11-1).

The built-in authentication forms make certain assumptions about the user model that they are working with. If you’re using a custom User model, it may be necessary to define your own forms for the authentication system.

Table 11-1: Django’s built-in authentication forms

Form Name Description
AdminPasswordChangeForm A form used in the admin interface to change a user’s password. Takes the user as the first positional argument.
AuthenticationForm A form for logging a user in. Takes request as its first positional argument, which is stored on the form instance for use by sub-classes.
PasswordChangeForm A form for allowing a user to change their password.
PasswordResetForm A form for generating and emailing a one-time use link to reset a user’s password.
SetPasswordForm A form that lets a user change their password without entering the old password.
UserChangeForm A form used in the admin interface to change a user’s information and permissions.
UserCreationForm A form for creating a new user.

Authentication Data in Templates

The currently logged-in user and their permissions are made available in the template context when you use RequestContext.

Users

When rendering a template RequestContext, the currently logged-in user, either a User instance or an AnonymousUser instance, is stored in the template variable
{{ user }}:

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

This template context variable is not available if a RequestContext is not being used.

Permissions

The currently logged-in user’s permissions are stored in the template variable {{ perms }}. This is an instance of django.contrib.auth.context_processors.PermWrapper, which is a template-friendly proxy of permissions. In the {{ perms }} object, single-attribute lookup is a proxy to User.has_module_perms. This example would display True if the logged-in user had any permissions in the foo app:

{{ perms.foo }}

Two-level-attribute lookup is a proxy to User.has_perm. This example would display True if the logged-in user had the permission foo.can_vote:

{{ perms.foo.can_vote }}

Thus, you can check permissions in template {% if %} statements:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.can_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

It is possible to also look permissions up by {% if in %} statements. For example:

{% if 'foo' in perms %}
    {% if 'foo.can_vote' in perms %}
        <p>In lookup works, too.</p>
    {% endif %}
{% endif %}