This document explains the usage of Django’s authentication system in itsdefault configuration. This configuration has evolved to serve the most commonproject needs, handling a reasonably wide range of tasks, and has a carefulimplementation of passwords and permissions. For projects where authenticationneeds differ from the default, Django supports extensive extension andcustomization of authentication.
Django authentication provides both authentication and authorization togetherand is generally referred to as the authentication system, as these featuresare somewhat coupled.
User
objects¶
User
objects are the core of theauthentication system. They typically represent the people interacting withyour site and are used to enable things like restricting access, registeringuser profiles, associating content with creators etc. Only one class of userexists in Django’s authentication framework, i.e., 'superusers'
or admin 'staff'
users are just user objects withspecial attributes set, not different classes of user objects.
The primary attributes of the default user are:
See the full API documentation
forfull reference, the documentation that follows is more task oriented.
Creating users¶
The most direct way to create users is to use the includedcreate_user()
helper function:
>>> from django.contrib.auth.models import User>>> user = User.objects.create_user("john", "lennon@thebeatles.com", "johnpassword")# At this point, user is a User object that has already been saved# to the database. You can continue to change its attributes# if you want to change other fields.>>> user.last_name = "Lennon">>> user.save()
If you have the Django admin installed, you can also create usersinteractively.
Creating superusers¶
Create superusers using the createsuperuser
command:
$ python manage.py createsuperuser --username=joe --email=joe@example.com
...\> py manage.py createsuperuser --username=joe --email=joe@example.com
You will be prompted for a password. After you enter one, the user will becreated immediately. If you leave off the --username
or --email
options, it willprompt you for those values.
Changing passwords¶
Django does not store raw (clear text) passwords on the user model, but onlya hash (see documentation of how passwords are managed for full details). Because of this, do not attempt tomanipulate the password attribute of the user directly. This is why a helperfunction is used when creating a user.
To change a user’s password, you have several options:
manage.py changepassword *username*
offers a methodof changing a user’s password from the command line. It prompts you tochange the password of a given user which you must enter twice. Ifthey both match, the new password will be changed immediately. If youdo not supply a user, the command will attempt to change the passwordwhose username matches the current system user.
You can also change a password programmatically, usingset_password()
:
>>> from django.contrib.auth.models import User>>> u = User.objects.get(username="john")>>> u.set_password("new password")>>> u.save()
If you have the Django admin installed, you can also change user’s passwordson the authentication system’s admin pages.
Django also provides views and forms that may be used to allow users to change their ownpasswords.
Changing a user’s password will log out all their sessions. SeeSession invalidation on password change for details.
Authenticating users¶
authenticate
(request=None, **credentials)¶Use authenticate() to verify a set ofcredentials. It takes credentials as keyword arguments,
username
andpassword
for the default case, checks them against eachauthentication backend, and returns aUser
object if the credentials arevalid for a backend. If the credentials aren’t valid for any backend or ifa backend raisesPermissionDenied
, itreturnsNone
. For example:from django.contrib.auth import authenticateuser = authenticate(username="john", password="secret")if user is not None: # A backend authenticated the credentials ...else: # No backend authenticated the credentials ...
request
is an optionalHttpRequest
which ispassed on theauthenticate()
method of the authentication backends.Note
This is a low level way to authenticate a set of credentials; forexample, it’s used by the
RemoteUserMiddleware
. Unlessyou are writing your own authentication system, you probably won’t usethis. Rather if you’re looking for a way to login a user, use theLoginView.
Permissions and Authorization¶
Django comes with a built-in permissions system. It provides a way to assignpermissions to specific users and groups of users.
It’s used by the Django admin site, but you’re welcome to use it in your owncode.
The Django admin site uses permissions as follows:
- Access to view objects is limited to users with the “view” or “change”permission for that type of object.
- Access to view the “add” form and add an object is limited to users withthe “add” permission for that type of object.
- Access to view the change list, view the “change” form and change anobject is limited to users with the “change” permission for that type ofobject.
- Access to delete an object is limited to users with the “delete”permission for that type of object.
Permissions can be set not only per type of object, but also per specificobject instance. By using thehas_view_permission()
,has_add_permission()
,has_change_permission()
andhas_delete_permission()
methods providedby the ModelAdmin
class, it is possible tocustomize permissions for different object instances of the same type.
User
objects have two many-to-manyfields: groups
and user_permissions
.User
objects can access their relatedobjects in the same way as any other Django model:
myuser.groups.set([group_list])myuser.groups.add(group, group, ...)myuser.groups.remove(group, group, ...)myuser.groups.clear()myuser.user_permissions.set([permission_list])myuser.user_permissions.add(permission, permission, ...)myuser.user_permissions.remove(permission, permission, ...)myuser.user_permissions.clear()
Default permissions¶
When django.contrib.auth
is listed in your INSTALLED_APPS
setting, it will ensure that four default permissions – add, change, delete,and view – are created for each Django model defined in one of your installedapplications.
These permissions will be created when you run manage.py migrate
; the first time you run migrate
after addingdjango.contrib.auth
to INSTALLED_APPS
, the default permissionswill be created for all previously-installed models, as well as for any newmodels being installed at that time. Afterward, it will create defaultpermissions for new models each time you run manage.py migrate
(the function that creates permissions is connected to thepost_migrate
signal).
Assuming you have an application with anapp_label
foo
and a model named Bar
,to test for basic permissions you should use:
- add:
user.has_perm('foo.add_bar')
- change:
user.has_perm('foo.change_bar')
- delete:
user.has_perm('foo.delete_bar')
- view:
user.has_perm('foo.view_bar')
The Permission
model is rarely accesseddirectly.
Groups¶
django.contrib.auth.models.Group
models are a generic way ofcategorizing users so you can apply permissions, or some other label, to thoseusers. A user can belong to any number of groups.
A user in a group automatically has the permissions granted to that group. Forexample, if the group Site editors
has the permissioncan_edit_home_page
, any user in that group will have that permission.
Beyond permissions, groups are a convenient way to categorize users to givethem some label, or extended functionality. For example, you could create agroup 'Special users'
, and you could write code that could, say, give themaccess to a members-only portion of your site, or send them members-only emailmessages.
Programmatically creating permissions¶
While custom permissions can be defined withina model’s Meta
class, you can also create permissions directly. Forexample, you can create the can_publish
permission for a BlogPost
modelin myapp
:
from myapp.models import BlogPostfrom django.contrib.auth.models import Permissionfrom django.contrib.contenttypes.models import ContentTypecontent_type = ContentType.objects.get_for_model(BlogPost)permission = Permission.objects.create( codename="can_publish", name="Can Publish Posts", content_type=content_type,)
The permission can then be assigned to aUser
via its user_permissions
attribute or to a Group
via itspermissions
attribute.
Proxy models need their own content type
If you want to create permissions for a proxy model, pass for_concrete_model=False
toContentTypeManager.get_for_model()
to get the appropriateContentType
:
content_type = ContentType.objects.get_for_model( BlogPostProxy, for_concrete_model=False)
Permission caching¶
The ModelBackend
caches permissions onthe user object after the first time they need to be fetched for a permissionscheck. This is typically fine for the request-response cycle since permissionsaren’t typically checked immediately after they are added (in the admin, forexample). If you are adding permissions and checking them immediatelyafterward, in a test or view for example, the easiest solution is to re-fetchthe user from the database. For example:
from django.contrib.auth.models import Permission, Userfrom django.contrib.contenttypes.models import ContentTypefrom django.shortcuts import get_object_or_404from myapp.models import BlogPostdef user_gains_perms(request, user_id): user = get_object_or_404(User, pk=user_id) # any permission check will cache the current set of permissions user.has_perm("myapp.change_blogpost") content_type = ContentType.objects.get_for_model(BlogPost) permission = Permission.objects.get( codename="change_blogpost", content_type=content_type, ) user.user_permissions.add(permission) # Checking the cached permission set user.has_perm("myapp.change_blogpost") # False # Request new instance of User # Be aware that user.refresh_from_db() won't clear the cache. user = get_object_or_404(User, pk=user_id) # Permission cache is repopulated from the database user.has_perm("myapp.change_blogpost") # True ...
Proxy models¶
Proxy models work exactly the same way as concrete models. Permissions arecreated using the own content type of the proxy model. Proxy models don’tinherit the permissions of the concrete model they subclass:
class Person(models.Model): class Meta: permissions = [("can_eat_pizzas", "Can eat pizzas")]class Student(Person): class Meta: proxy = True permissions = [("can_deliver_pizzas", "Can deliver pizzas")]
>>> # Fetch the content type for the proxy model.>>> content_type = ContentType.objects.get_for_model(Student, for_concrete_model=False)>>> student_permissions = Permission.objects.filter(content_type=content_type)>>> [p.codename for p in student_permissions]['add_student', 'change_student', 'delete_student', 'view_student','can_deliver_pizzas']>>> for permission in student_permissions:... user.user_permissions.add(permission)...>>> user.has_perm("app.add_person")False>>> user.has_perm("app.can_eat_pizzas")False>>> user.has_perms(("app.add_student", "app.can_deliver_pizzas"))True
Authentication in web requests¶
Django uses sessions and middleware to hook theauthentication system into request objects
.
These provide a request.user
attributeon every request which represents the current user. If the current user has notlogged in, this attribute will be set to an instanceof AnonymousUser
, otherwise it will be aninstance of User
.
You can tell them apart withis_authenticated
, like so:
if request.user.is_authenticated: # Do something for authenticated users. ...else: # Do something for anonymous users. ...
How to log a user in¶
If you have an authenticated user you want to attach to the current session- this is done with a login() function.
login
(request, user, backend=None)¶To log a user in, from a view, use login(). Ittakes an
HttpRequest
object and aUser
object.login() saves the user’s ID in the session,using Django’s session framework.Note that any data set during the anonymous session is retained in thesession after a user logs in.
This example shows how you might use bothauthenticate() andlogin():
from django.contrib.auth import authenticate, logindef my_view(request): username = request.POST["username"] password = request.POST["password"] user = authenticate(request, username=username, password=password) if user is not None: login(request, user) # Redirect to a success page. ... else: # Return an 'invalid login' error message. ...
Selecting the authentication backend¶
When a user logs in, the user’s ID and the backend that was used forauthentication are saved in the user’s session. This allows the sameauthentication backend to fetch the user’sdetails on a future request. The authentication backend to save in the sessionis selected as follows:
- Use the value of the optional
backend
argument, if provided. - Use the value of the
user.backend
attribute, if present. This allowspairing authenticate() andlogin():authenticate()sets theuser.backend
attribute on the user object it returns. - Use the
backend
inAUTHENTICATION_BACKENDS
, if there is onlyone. - Otherwise, raise an exception.
In cases 1 and 2, the value of the backend
argument or the user.backend
attribute should be a dotted import path string (like that found inAUTHENTICATION_BACKENDS
), not the actual backend class.
How to log a user out¶
logout
(request)¶To log out a user who has been logged in viadjango.contrib.auth.login(), usedjango.contrib.auth.logout() within your view. It takes an
HttpRequest
object and has no return value.Example:from django.contrib.auth import logoutdef logout_view(request): logout(request) # Redirect to a success page.
Note that logout() doesn’t throw any errors ifthe user wasn’t logged in.
When you call logout(), the session data forthe current request is completely cleaned out. All existing data isremoved. This is to prevent another person from using the same web browserto log in and have access to the previous user’s session data. If you wantto put anything into the session that will be available to the userimmediately after logging out, do that after callingdjango.contrib.auth.logout().
Limiting access to logged-in users¶
The raw way¶
The raw way to limit access to pages is to checkrequest.user.is_authenticated
and either redirect to alogin page:
from django.conf import settingsfrom django.shortcuts import redirectdef my_view(request): if not request.user.is_authenticated: return redirect(f"{settings.LOGIN_URL}?next={request.path}") # ...
…or display an error message:
from django.shortcuts import renderdef my_view(request): if not request.user.is_authenticated: return render(request, "myapp/login_error.html") # ...
The login_required
decorator¶
login_required
(redirect_field_name='next', login_url=None)¶As a shortcut, you can use the convenientlogin_required() decorator:
from django.contrib.auth.decorators import login_required@login_requireddef my_view(request): ...
login_required() does the following:
- If the user isn’t logged in, redirect to
settings.LOGIN_URL
, passing the current absolutepath in the query string. Example:/accounts/login/?next=/polls/3/
. - If the user is logged in, execute the view normally. The view code isfree to assume the user is logged in.
By default, the path that the user should be redirected to uponsuccessful authentication is stored in a query string parameter called
"next"
. If you would prefer to use a different name for this parameter,login_required() takes anoptionalredirect_field_name
parameter:from django.contrib.auth.decorators import login_required@login_required(redirect_field_name="my_redirect_field")def my_view(request): ...
Note that if you provide a value to
redirect_field_name
, you will mostlikely need to customize your login template as well, since the templatecontext variable which stores the redirect path will use the value ofredirect_field_name
as its key rather than"next"
(the default).login_required() also takes anoptional
login_url
parameter. Example:from django.contrib.auth.decorators import login_required@login_required(login_url="/accounts/login/")def my_view(request): ...
Note that if you don’t specify the
login_url
parameter, you’ll need toensure that thesettings.LOGIN_URL
and your loginview are properly associated. For example, using the defaults, add thefollowing lines to your URLconf:from django.contrib.auth import views as auth_viewspath("accounts/login/", auth_views.LoginView.as_view()),
The
settings.LOGIN_URL
also accepts view functionnames and named URL patterns. This allows youto freely remap your login view within your URLconf without having toupdate the setting.- If the user isn’t logged in, redirect to
Note
The login_required
decorator does NOT check the is_active
flag on auser, but the default AUTHENTICATION_BACKENDS
reject inactiveusers.
See also
If you are writing custom views for Django’s admin (or need the sameauthorization check that the built-in views use), you may find thedjango.contrib.admin.views.decorators.staff_member_required()
decorator a useful alternative to login_required()
.
The LoginRequiredMixin
mixin¶
When using class-based views, you canachieve the same behavior as with login_required
by using theLoginRequiredMixin
. This mixin should be at the leftmost position in theinheritance list.
- class
LoginRequiredMixin
¶ If a view is using this mixin, all requests by non-authenticated users willbe redirected to the login page or shown an HTTP 403 Forbidden error,depending on theraise_exception parameter.
You can set any of the parameters ofAccessMixin to customize the handlingof unauthorized users:
from django.contrib.auth.mixins import LoginRequiredMixinclass MyView(LoginRequiredMixin, View): login_url = "/login/" redirect_field_name = "redirect_to"
Note
Just as the login_required
decorator, this mixin does NOT check theis_active
flag on a user, but the defaultAUTHENTICATION_BACKENDS
reject inactive users.
Limiting access to logged-in users that pass a test¶
To limit access based on certain permissions or some other test, you’d doessentially the same thing as described in the previous section.
You can run your test on request.user
inthe view directly. For example, this view checks to make sure the user has anemail in the desired domain and if not, redirects to the login page:
from django.shortcuts import redirectdef my_view(request): if not request.user.email.endswith("@example.com"): return redirect("/login/?next=%s" % request.path) # ...
user_passes_test
(test_func, login_url=None, redirect_field_name='next')¶As a shortcut, you can use the convenient
user_passes_test
decoratorwhich performs a redirect when the callable returnsFalse
:from django.contrib.auth.decorators import user_passes_testdef email_check(user): return user.email.endswith("@example.com")@user_passes_test(email_check)def my_view(request): ...
user_passes_test() takes a requiredargument: a callable that takes a
User
object and returnsTrue
ifthe user is allowed to view the page. Note thatuser_passes_test() does notautomatically check that theUser
isnot anonymous.user_passes_test() takes twooptional arguments:
login_url
- Lets you specify the URL that users who don’t pass the test will beredirected to. It may be a login page and defaults to
settings.LOGIN_URL
if you don’t specify one. redirect_field_name
- Same as for login_required().Setting it to
None
removes it from the URL, which you may want to doif you are redirecting users that don’t pass the test to a non-loginpage where there’s no “next page”.
For example:
@user_passes_test(email_check, login_url="/login/")def my_view(request): ...
- class
UserPassesTestMixin
¶ When using class-based views, youcan use the
UserPassesTestMixin
to do this.test_func
()¶You have to override the
test_func()
method of the class toprovide the test that is performed. Furthermore, you can set any of theparameters of AccessMixin tocustomize the handling of unauthorized users:from django.contrib.auth.mixins import UserPassesTestMixinclass MyView(UserPassesTestMixin, View): def test_func(self): return self.request.user.email.endswith("@example.com")
get_test_func
()¶You can also override the
get_test_func()
method to have the mixinuse a differently named function for its checks (instead oftest_func()).
Stacking
UserPassesTestMixin
Due to the way
UserPassesTestMixin
is implemented, you cannot stackthem in your inheritance list. The following does NOT work:class TestMixin1(UserPassesTestMixin): def test_func(self): return self.request.user.email.endswith("@example.com")class TestMixin2(UserPassesTestMixin): def test_func(self): return self.request.user.username.startswith("django")class MyView(TestMixin1, TestMixin2, View): ...
If
TestMixin1
would callsuper()
and take that result intoaccount,TestMixin1
wouldn’t work standalone anymore.
The permission_required
decorator¶
permission_required
(perm, login_url=None, raise_exception=False)¶It’s a relatively common task to check whether a user has a particularpermission. For that reason, Django provides a shortcut for that case: thepermission_required() decorator.:
from django.contrib.auth.decorators import permission_required@permission_required("polls.add_choice")def my_view(request): ...
Just like the
has_perm()
method,permission names take the form"<app label>.<permission codename>"
(i.e.polls.add_choice
for a permission on a model in thepolls
application).The decorator may also take an iterable of permissions, in which case theuser must have all of the permissions in order to access the view.
Note that permission_required()also takes an optional
login_url
parameter:from django.contrib.auth.decorators import permission_required@permission_required("polls.add_choice", login_url="/loginpage/")def my_view(request): ...
As in the login_required() decorator,
login_url
defaults tosettings.LOGIN_URL
.If the
raise_exception
parameter is given, the decorator will raisePermissionDenied
, prompting the 403(HTTP Forbidden) view instead of redirecting to thelogin page.If you want to use
raise_exception
but also give your users a chance tologin first, you can add thelogin_required() decorator:from django.contrib.auth.decorators import login_required, permission_required@login_required@permission_required("polls.add_choice", raise_exception=True)def my_view(request): ...
This also avoids a redirect loop when LoginView’s
redirect_authenticated_user=True
and the logged-in user doesn’t haveall of the required permissions.
The PermissionRequiredMixin
mixin¶
To apply permission checks to class-based views, you can use the PermissionRequiredMixin
:
- class
PermissionRequiredMixin
¶ This mixin, just like the
permission_required
decorator, checks whether the user accessing a view has all givenpermissions. You should specify the permission (or an iterable ofpermissions) using thepermission_required
parameter:from django.contrib.auth.mixins import PermissionRequiredMixinclass MyView(PermissionRequiredMixin, View): permission_required = "polls.add_choice" # Or multiple of permissions: permission_required = ["polls.view_choice", "polls.change_choice"]
You can set any of the parameters ofAccessMixin to customize the handlingof unauthorized users.
You may also override these methods:
get_permission_required
()¶Returns an iterable of permission names used by the mixin. Defaults tothe
permission_required
attribute, converted to a tuple ifnecessary.
has_permission
()¶Returns a boolean denoting whether the current user has permission toexecute the decorated view. By default, this returns the result ofcalling
has_perms()
with thelist of permissions returned by get_permission_required().
Redirecting unauthorized requests in class-based views¶
To ease the handling of access restrictions in class-based views, the AccessMixin
can be used to configurethe behavior of a view when access is denied. Authenticated users are deniedaccess with an HTTP 403 Forbidden response. Anonymous users are redirected tothe login page or shown an HTTP 403 Forbidden response, depending on theraise_exception attribute.
- class
AccessMixin
¶ login_url
¶Default return value for get_login_url(). Defaults to
None
in which case get_login_url() falls back tosettings.LOGIN_URL
.
permission_denied_message
¶Default return value for get_permission_denied_message().Defaults to an empty string.
redirect_field_name
¶Default return value for get_redirect_field_name(). Defaults to
"next"
.
raise_exception
¶If this attribute is set to
True
, aPermissionDenied
exception is raisedwhen the conditions are not met. WhenFalse
(the default),anonymous users are redirected to the login page.
get_login_url
()¶Returns the URL that users who don’t pass the test will be redirectedto. Returns login_url if set, or
settings.LOGIN_URL
otherwise.
get_permission_denied_message
()¶When raise_exception is
True
, this method can be used tocontrol the error message passed to the error handler for display tothe user. Returns the permission_denied_message attribute bydefault.
get_redirect_field_name
()¶Returns the name of the query parameter that will contain the URL theuser should be redirected to after a successful login. If you set thisto
None
, a query parameter won’t be added. Returns theredirect_field_name attribute by default.
handle_no_permission
()¶Depending on the value of
raise_exception
, the method either raisesaPermissionDenied
exception orredirects the user to thelogin_url
, optionally including theredirect_field_name
if it is set.
Session invalidation on password change¶
If your AUTH_USER_MODEL
inherits fromAbstractBaseUser
or implements its ownget_session_auth_hash()
method, authenticated sessions will include the hash returned by this function.In the AbstractBaseUser
case, this is anHMAC of the password field. Django verifies that the hash in the session foreach request matches the one that’s computed during the request. This allows auser to log out all of their sessions by changing their password.
The default password change views included with Django,PasswordChangeView and theuser_change_password
view in the django.contrib.auth
admin, updatethe session with the new password hash so that a user changing their ownpassword won’t log themselves out. If you have a custom password change viewand wish to have similar behavior, use the update_session_auth_hash()function.
update_session_auth_hash
(request, user)¶This function takes the current request and the updated user object fromwhich the new session hash will be derived and updates the session hashappropriately. It also rotates the session key so that a stolen sessioncookie will be invalidated.
Example usage:
from django.contrib.auth import update_session_auth_hashdef password_change(request): if request.method == "POST": form = PasswordChangeForm(user=request.user, data=request.POST) if form.is_valid(): form.save() update_session_auth_hash(request, form.user) else: ...
Note
Sinceget_session_auth_hash()
is based on SECRET_KEY
, secret key values must berotated to avoid invalidating existing sessions when updating your site touse a new secret. See SECRET_KEY_FALLBACKS
for details.
Authentication Views¶
Django provides several views that you can use for handling login, logout, andpassword management. These make use of the stock auth forms but you can pass in your own forms as well.
Django provides no default template for the authentication views. You shouldcreate your own templates for the views you want to use. The template contextis documented in each view, see All authentication views.
Using the views¶
There are different methods to implement these views in your project. Theeasiest way is to include the provided URLconf in django.contrib.auth.urls
in your own URLconf, for example:
urlpatterns = [ path("accounts/", include("django.contrib.auth.urls")),]
This will include the following URL patterns:
accounts/login/ [name='login']accounts/logout/ [name='logout']accounts/password_change/ [name='password_change']accounts/password_change/done/ [name='password_change_done']accounts/password_reset/ [name='password_reset']accounts/password_reset/done/ [name='password_reset_done']accounts/reset/<uidb64>/<token>/ [name='password_reset_confirm']accounts/reset/done/ [name='password_reset_complete']
The views provide a URL name for easier reference. See the URLdocumentation for details on using named URL patterns.
If you want more control over your URLs, you can reference a specific view inyour URLconf:
from django.contrib.auth import views as auth_viewsurlpatterns = [ path("change-password/", auth_views.PasswordChangeView.as_view()),]
The views have optional arguments you can use to alter the behavior of theview. For example, if you want to change the template name a view uses, you canprovide the template_name
argument. A way to do this is to provide keywordarguments in the URLconf, these will be passed on to the view. For example:
urlpatterns = [ path( "change-password/", auth_views.PasswordChangeView.as_view(template_name="change-password.html"), ),]
All views are class-based, which allowsyou to easily customize them by subclassing.
All authentication views¶
This is a list with all the views django.contrib.auth
provides. Forimplementation details see Using the views.
- class
LoginView
¶ URL name:
login
See the URL documentation for details on usingnamed URL patterns.
Methods and Attributes
template_name
¶The name of a template to display for the view used to log the user in.Defaults to
registration/login.html
.
next_page
¶The URL to redirect to after login. Defaults to
LOGIN_REDIRECT_URL
.
redirect_field_name
¶The name of a
GET
field containing the URL to redirect to afterlogin. Defaults tonext
. Overrides theget_default_redirect_url() URL if the givenGET
parameter ispassed.
authentication_form
¶A callable (typically a form class) to use for authentication. Defaultsto AuthenticationForm.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
redirect_authenticated_user
¶A boolean that controls whether or not authenticated users accessingthe login page will be redirected as if they had just successfullylogged in. Defaults to
False
.Warning
If you enable
redirect_authenticated_user
, other websites willbe able to determine if their visitors are authenticated on yoursite by requesting redirect URLs to image files on your website. Toavoid this “social media fingerprinting” informationleakage, host all images and your favicon on a separate domain.Enabling
redirect_authenticated_user
can also result in aredirect loop when using the permission_required() decoratorunless theraise_exception
parameter is used.
success_url_allowed_hosts
¶A
set
of hosts, in addition torequest.get_host()
, that are safe for redirectingafter login. Defaults to an emptyset
.
get_default_redirect_url
()¶Returns the URL to redirect to after login. The default implementationresolves and returns next_page if set, or
LOGIN_REDIRECT_URL
otherwise.
Here’s what
LoginView
does:- If called via
GET
, it displays a login form that POSTs to thesame URL. More on this in a bit. - If called via
POST
with user submitted credentials, it tries to logthe user in. If login is successful, the view redirects to the URLspecified innext
. Ifnext
isn’t provided, it redirects tosettings.LOGIN_REDIRECT_URL
(whichdefaults to/accounts/profile/
). If login isn’t successful, itredisplays the login form.
It’s your responsibility to provide the html for the login template, called
registration/login.html
by default. This template gets passedfour template context variables:form
: AForm
object representing theAuthenticationForm.next
: The URL to redirect to after successful login. This maycontain a query string, too.site
: The currentSite
,according to theSITE_ID
setting. If you don’t have thesite framework installed, this will be set to an instance ofRequestSite
, which derives thesite name and domain from the currentHttpRequest
.site_name
: An alias forsite.name
. If you don’t have the siteframework installed, this will be set to the value ofrequest.META['SERVER_NAME']
.For more on sites, see The “sites” framework.
If you’d prefer not to call the template
registration/login.html
,you can pass thetemplate_name
parameter via the extra arguments totheas_view
method in your URLconf. For example, this URLconf line wouldusemyapp/login.html
instead:path("accounts/login/", auth_views.LoginView.as_view(template_name="myapp/login.html")),
You can also specify the name of the
GET
field which contains the URLto redirect to after login usingredirect_field_name
. By default, thefield is callednext
.Here’s a sample
registration/login.html
template you can use as astarting point. It assumes you have abase.html
template thatdefines acontent
block:{% extends "base.html" %}{% block content %}{% if form.errors %}<p>Your username and password didn't match. Please try again.</p>{% endif %}{% if next %} {% if user.is_authenticated %} <p>Your account doesn't have access to this page. To proceed, please login with an account that has access.</p> {% else %} <p>Please login to see this page.</p> {% endif %}{% endif %}<form method="post" action="{% url 'login' %}">{% csrf_token %}<table><tr> <td>{{ form.username.label_tag }}</td> <td>{{ form.username }}</td></tr><tr> <td>{{ form.password.label_tag }}</td> <td>{{ form.password }}</td></tr></table><input type="submit" value="login"><input type="hidden" name="next" value="{{ next }}"></form>{# Assumes you set up the password_reset view in your URLconf #}<p><a href="{% url 'password_reset' %}">Lost password?</a></p>{% endblock %}
If you have customized authentication (see Customizing Authentication) you can use a custom authentication form bysetting the
authentication_form
attribute. This form must accept arequest
keyword argument in its__init__()
method and provide aget_user()
method which returns the authenticated user object (thismethod is only ever called after successful form validation).
- class
LogoutView
¶ Logs a user out on
POST
requests.Deprecated since version 4.1: Support for logging out on
GET
requests is deprecated and will beremoved in Django 5.0.URL name:
logout
Attributes:
next_page
¶The URL to redirect to after logout. Defaults to
LOGOUT_REDIRECT_URL
.
template_name
¶The full name of a template to display after logging the user out.Defaults to
registration/logged_out.html
.
redirect_field_name
¶The name of a
GET
field containing the URL to redirect to after logout. Defaults to'next'
. Overrides thenext_page URL if the givenGET
parameter ispassed.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
success_url_allowed_hosts
¶A
set
of hosts, in addition torequest.get_host()
, that are safe for redirectingafter logout. Defaults to an emptyset
.
Template context:
title
: The string “Logged out”, localized.site
: The currentSite
,according to theSITE_ID
setting. If you don’t have thesite framework installed, this will be set to an instance ofRequestSite
, which derives thesite name and domain from the currentHttpRequest
.site_name
: An alias forsite.name
. If you don’t have the siteframework installed, this will be set to the value ofrequest.META['SERVER_NAME']
.For more on sites, see The “sites” framework.
logout_then_login
(request, login_url=None)¶Logs a user out on
POST
requests, then redirects to the login page.URL name: No default URL provided
Optional arguments:
login_url
: The URL of the login page to redirect to.Defaults tosettings.LOGIN_URL
if not supplied.
Deprecated since version 4.1: Support for logging out on
GET
requests is deprecated and will beremoved in Django 5.0.
- class
PasswordChangeView
¶ URL name:
password_change
Allows a user to change their password.
Attributes:
template_name
¶The full name of a template to use for displaying the password changeform. Defaults to
registration/password_change_form.html
if notsupplied.
success_url
¶The URL to redirect to after a successful password change. Defaults to
'password_change_done'
.
form_class
¶A custom “change password” form which must accept a
user
keywordargument. The form is responsible for actually changing the user’spassword. Defaults toPasswordChangeForm.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
Template context:
form
: The password change form (seeform_class
above).
- class
PasswordChangeDoneView
¶ URL name:
password_change_done
The page shown after a user has changed their password.
Attributes:
template_name
¶The full name of a template to use. Defaults to
registration/password_change_done.html
if not supplied.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
- class
PasswordResetView
¶ URL name:
password_reset
Allows a user to reset their password by generating a one-time use linkthat can be used to reset the password, and sending that link to theuser’s registered email address.
This view will send an email if the following conditions are met:
- The email address provided exists in the system.
- The requested user is active (
User.is_active
isTrue
). - The requested user has a usable password. Users flagged with an unusablepassword (see
set_unusable_password()
) aren’tallowed to request a password reset to prevent misuse when using anexternal authentication source like LDAP.
If any of these conditions are not met, no email will be sent, but theuser won’t receive any error message either. This prevents informationleaking to potential attackers. If you want to provide an error message inthis case, you can subclassPasswordResetForm and use the
form_class
attribute.Note
Be aware that sending an email costs extra time, hence you may bevulnerable to an email address enumeration timing attack due to adifference between the duration of a reset request for an existingemail address and the duration of a reset request for a nonexistentemail address. To reduce the overhead, you can use a 3rd party packagethat allows to send emails asynchronously, e.g. django-mailer.
Attributes:
template_name
¶The full name of a template to use for displaying the password resetform. Defaults to
registration/password_reset_form.html
if notsupplied.
form_class
¶Form that will be used to get the email of the user to reset thepassword for. Defaults toPasswordResetForm.
email_template_name
¶The full name of a template to use for generating the email with thereset password link. Defaults to
registration/password_reset_email.html
if not supplied.
subject_template_name
¶The full name of a template to use for the subject of the email withthe reset password link. Defaults to
registration/password_reset_subject.txt
if not supplied.
token_generator
¶Instance of the class to check the one time link. This will default to
default_token_generator
, it’s an instance ofdjango.contrib.auth.tokens.PasswordResetTokenGenerator
.
success_url
¶The URL to redirect to after a successful password reset request.Defaults to
'password_reset_done'
.
from_email
¶A valid email address. By default Django uses the
DEFAULT_FROM_EMAIL
.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
html_email_template_name
¶The full name of a template to use for generating atext/html multipart email with the password reset link. Bydefault, HTML email is not sent.
extra_email_context
¶A dictionary of context data that will be available in the emailtemplate. It can be used to override default template context valueslisted below e.g.
domain
.
Template context:
form
: The form (seeform_class
above) for resetting the user’spassword.
Email template context:
email
: An alias foruser.email
user
: The currentUser
,according to theemail
form field. Only active users are able toreset their passwords (User.is_active is True
).site_name
: An alias forsite.name
. If you don’t have the siteframework installed, this will be set to the value ofrequest.META['SERVER_NAME']
.For more on sites, see The “sites” framework.domain
: An alias forsite.domain
. If you don’t have the siteframework installed, this will be set to the value ofrequest.get_host()
.protocol
: http or httpsuid
: The user’s primary key encoded in base 64.token
: Token to check that the reset link is valid.
Sample
registration/password_reset_email.html
(email body template):Someone asked for password reset for email {{ email }}. Follow the link below:{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}
The same template context is used for subject template. Subject must besingle line plain text string.
- class
PasswordResetDoneView
¶ URL name:
password_reset_done
The page shown after a user has been emailed a link to reset theirpassword. This view is called by default if the PasswordResetViewdoesn’t have an explicit
success_url
URL set.Note
If the email address provided does not exist in the system, the user isinactive, or has an unusable password, the user will still beredirected to this view but no email will be sent.
Attributes:
template_name
¶The full name of a template to use. Defaults to
registration/password_reset_done.html
if not supplied.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
- class
PasswordResetConfirmView
¶ URL name:
password_reset_confirm
Presents a form for entering a new password.
Keyword arguments from the URL:
uidb64
: The user’s id encoded in base 64.token
: Token to check that the password is valid.
Attributes:
template_name
¶The full name of a template to display the confirm password view.Default value is
registration/password_reset_confirm.html
.
token_generator
¶Instance of the class to check the password. This will default to
default_token_generator
, it’s an instance ofdjango.contrib.auth.tokens.PasswordResetTokenGenerator
.
post_reset_login
¶A boolean indicating if the user should be automatically authenticatedafter a successful password reset. Defaults to
False
.
post_reset_login_backend
¶A dotted path to the authentication backend to use when authenticatinga user if
post_reset_login
isTrue
. Required only if you havemultipleAUTHENTICATION_BACKENDS
configured. Defaults toNone
.
form_class
¶Form that will be used to set the password. Defaults toSetPasswordForm.
success_url
¶URL to redirect after the password reset done. Defaults to
'password_reset_complete'
.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
reset_url_token
¶Token parameter displayed as a component of password reset URLs.Defaults to
'set-password'
.
Template context:
form
: The form (seeform_class
above) for setting the new user’spassword.validlink
: Boolean, True if the link (combination ofuidb64
andtoken
) is valid or unused yet.
- class
PasswordResetCompleteView
¶ URL name:
password_reset_complete
Presents a view which informs the user that the password has beensuccessfully changed.
Attributes:
template_name
¶The full name of a template to display the view. Defaults to
registration/password_reset_complete.html
.
extra_context
¶A dictionary of context data that will be added to the default contextdata passed to the template.
Helper functions¶
redirect_to_login
(next, login_url=None, redirect_field_name='next')¶Redirects to the login page, and then back to another URL after asuccessful login.
Required arguments:
next
: The URL to redirect to after a successful login.
Optional arguments:
login_url
: The URL of the login page to redirect to.Defaults tosettings.LOGIN_URL
if not supplied.redirect_field_name
: The name of aGET
field containing theURL to redirect to after log out. Overridesnext
if the givenGET
parameter is passed.
Built-in forms¶
If you don’t want to use the built-in views, but want the convenience of nothaving to write forms for this functionality, the authentication systemprovides several built-in forms located in django.contrib.auth.forms:
Note
The built-in authentication forms make certain assumptions about the usermodel that they are working with. If you’re using a custom user model, it may be necessary to define your own forms for theauthentication system. For more information, refer to the documentationabout using the built-in authentication forms with custom user models.
- class
AdminPasswordChangeForm
¶ A form used in the admin interface to change a user’s password.
Takes the
user
as the first positional argument.
- class
AuthenticationForm
¶ A form for logging a user in.
Takes
request
as its first positional argument, which is stored on theform instance for use by sub-classes.confirm_login_allowed
(user)¶By default,
AuthenticationForm
rejects users whoseis_active
flag is set toFalse
. You may override this behavior with a custompolicy to determine which users can log in. Do this with a custom formthat subclassesAuthenticationForm
and overrides theconfirm_login_allowed()
method. This method should raise aValidationError
if the given user maynot log in.For example, to allow all users to log in regardless of “active”status:
from django.contrib.auth.forms import AuthenticationFormclass AuthenticationFormWithInactiveUsersOkay(AuthenticationForm): def confirm_login_allowed(self, user): pass
(In this case, you’ll also need to use an authentication backend thatallows inactive users, such as
AllowAllUsersModelBackend
.)Or to allow only some active users to log in:
class PickyAuthenticationForm(AuthenticationForm): def confirm_login_allowed(self, user): if not user.is_active: raise ValidationError( _("This account is inactive."), code="inactive", ) if user.username.startswith("b"): raise ValidationError( _("Sorry, accounts starting with 'b' aren't welcome here."), code="no_b_users", )
- class
PasswordChangeForm
¶ A form for allowing a user to change their password.
- class
PasswordResetForm
¶ A form for generating and emailing a one-time use link to reset auser’s password.
send_mail
(subject_template_name, email_template_name, context, from_email, to_email, html_email_template_name=None)¶Uses the arguments to send an
EmailMultiAlternatives
.Can be overridden to customize how the email is sent to the user.Parameters: - subject_template_name – the template for the subject.
- email_template_name – the template for the email body.
- context – context passed to the
subject_template
,email_template
, andhtml_email_template
(if it is notNone
). - from_email – the sender’s email.
- to_email – the email of the requester.
- html_email_template_name – the template for the HTML body;defaults to
None
, in which case a plain text email is sent.
By default,
save()
populates thecontext
with thesame variables thatPasswordResetView passes to itsemail context.
- class
SetPasswordForm
¶ A form that lets a user change their password without entering the oldpassword.
- class
UserChangeForm
¶ A form used in the admin interface to change a user’s information andpermissions.
- class
BaseUserCreationForm
¶ New in Django 4.2.
A
ModelForm
for creating a new user. This is therecommended base class if you need to customize the user creation form.It has three fields:
username
(from the user model),password1
,andpassword2
. It verifies thatpassword1
andpassword2
match,validates the password usingvalidate_password()
, andsets the user’s password usingset_password()
.
- class
UserCreationForm
¶ Inherits from BaseUserCreationForm. To help prevent confusion withsimilar usernames, the form doesn’t allow usernames that differ only incase.
Changed in Django 4.2:
In older versions, UserCreationForm didn’t save many-to-manyform fields for a custom user model.
In older versions, usernames that differ only in case are allowed.
Authentication data in templates¶
The currently logged-in user and their permissions are made available in thetemplate context when you useRequestContext
.
Technicality
Technically, these variables are only made available in the templatecontext if you use RequestContext
and the'django.contrib.auth.context_processors.auth'
context processor isenabled. It is in the default generated settings file. For more, see theRequestContext docs.
Users¶
When rendering a template RequestContext
, thecurrently logged-in user, either a User
instance or an AnonymousUser
instance, isstored 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 notbeing used.
Permissions¶
The currently logged-in user’s permissions are stored in the template variable{{ perms }}
. This is an instance ofdjango.contrib.auth.context_processors.PermWrapper
, which is atemplate-friendly proxy of permissions.
Evaluating a single-attribute lookup of {{ perms }}
as a boolean is a proxyto User.has_module_perms()
. For example, to check ifthe logged-in user has any permissions in the foo
app:
{% if perms.foo %}
Evaluating a two-level-attribute lookup as a boolean is a proxy toUser.has_perm()
. For example,to check if the logged-in user has the permission foo.add_vote
:
{% if perms.foo.add_vote %}
Here’s a more complete example of checking permissions in a template:
{% if perms.foo %} <p>You have permission to do something in the foo app.</p> {% if perms.foo.add_vote %} <p>You can vote!</p> {% endif %} {% if perms.foo.add_driving %} <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.add_vote' in perms %} <p>In lookup works, too.</p> {% endif %}{% endif %}
Managing users in the admin¶
When you have both django.contrib.admin
and django.contrib.auth
installed, the admin provides a convenient way to view and manage users,groups, and permissions. Users can be created and deleted like any Djangomodel. Groups can be created, and permissions can be assigned to users orgroups. A log of user edits to models made within the admin is also stored anddisplayed.
Creating users¶
You should see a link to “Users” in the “Auth”section of the main admin index page. The “Add user” admin page is differentthan standard admin pages in that it requires you to choose a username andpassword before allowing you to edit the rest of the user’s fields.
Also note: if you want a user account to be able to create users using theDjango admin site, you’ll need to give them permission to add users andchange users (i.e., the “Add user” and “Change user” permissions). If anaccount has permission to add users but not to change them, that account won’tbe able to add users. Why? Because if you have permission to add users, youhave the power to create superusers, which can then, in turn, change otherusers. So Django requires add and change permissions as a slight securitymeasure.
Be thoughtful about how you allow users to manage permissions. If you give anon-superuser the ability to edit users, this is ultimately the same as givingthem superuser status because they will be able to elevate permissions ofusers including themselves!
Changing passwords¶
User passwords are not displayed in the admin (nor stored in the database), butthe password storage details are displayed.Included in the display of this information is a link toa password change form that allows admins to change user passwords.