group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()
class validators.ASCIIUsernameValidator
A field validator allowing only ASCII letters and numbers, in addition to
@, ., +, -, and _.
class validators.UnicodeUsernameValidator
A field validator allowing Unicode characters, in addition to @, .,
+, -, and _. The default validator for User.username.
Login and logout signals
The auth framework uses the following signals that
can be used for notification when a user logs in or out.
user_logged_in
Sent when a user logs in successfully.
Arguments sent with this signal:
senderThe class of the user that just logged in.
requestThe current HttpRequest instance.
userThe user instance that just logged in.
Sent when the logout method is called.
senderAs above: the class of the user that just logged out or None
if the user was not authenticated.
requestThe current HttpRequest instance.
userThe user instance that just logged out or None if the
user was not authenticated.
Sent when the user failed to login successfully
senderThe name of the module used for authentication.
credentialsA dictionary of keyword arguments containing the user credentials that were
passed to authenticate() or your own custom
authentication backend. Credentials matching a set of ‘sensitive’ patterns,
(including password) will not be sent in the clear as part of the signal.
requestThe HttpRequest object, if one was provided to
authenticate().
Authentication backends
This section details the authentication backends that come with Django. For
information on how to use them and how to write your own authentication
backends, see the Other authentication sources section of the User authentication guide.
Available authentication backends
The following backends are available in django.contrib.auth.backends:
class BaseBackend[source]
A base class that provides default implementations for all required
methods. By default, it will reject any user and provide no permissions.
get_user_permissions(user_obj, obj=None)[source]
aget_user_permissions(user_obj, obj=None)
Asynchronous version: aget_user_permissions()
Returns an empty set.
Changed in Django 5.2: aget_user_permissions() function was added.
aget_group_permissions(user_obj, obj=None)
Asynchronous version: aget_group_permissions()
Returns an empty set.
Changed in Django 5.2: aget_group_permissions() function was added.
aget_all_permissions(user_obj, obj=None)
Asynchronous version: aget_all_permissions()
Uses get_user_permissions() and get_group_permissions() to
get the set of permission strings the user_obj has.
Changed in Django 5.2: aget_all_permissions() function was added.
ahas_perm(user_obj, perm, obj=None)
Asynchronous version: ahas_perm()
Uses get_all_permissions() to check if user_obj has the
permission string perm.
Changed in Django 5.2: ahas_perm() function was added.
class ModelBackend[source]
This is the default authentication backend used by Django. It
authenticates using credentials consisting of a user identifier and
password. For Django’s default user model, the user identifier is the
username, for custom user models it is the field specified by
USERNAME_FIELD (see Customizing Users and authentication).
It also handles the default permissions model as defined for
User and
PermissionsMixin.
has_perm(), get_all_permissions(), get_user_permissions(),
and get_group_permissions() allow an object to be passed as a
parameter for object-specific permissions, but this backend does not
implement them other than returning an empty set of permissions if
obj is not None.
with_perm() also allows an object to be passed as a parameter, but
unlike others methods it returns an empty queryset if obj
is not None.
authenticate(request, username=None, password=None, **kwargs)[source]
aauthenticate(request, username=None, password=None, **kwargs)
Asynchronous version: aauthenticate()
Tries to authenticate username with password by calling
User.check_password. If no username
is provided, it tries to fetch a username from kwargs using the
key CustomUser.USERNAME_FIELD. Returns an
authenticated user or None.
request is an HttpRequest and may be None
if it wasn’t provided to authenticate()
(which passes it on to the backend).
Changed in Django 5.2: aauthenticate() function was added.
aget_user_permissions(user_obj, obj=None)
Asynchronous version: aget_user_permissions()
Returns the set of permission strings the user_obj has from their
own user permissions. Returns an empty set if
is_anonymous or
is_active is False.
Changed in Django 5.2: aget_user_permissions() function was added.
aget_group_permissions(user_obj, obj=None)
Asynchronous version: aget_group_permissions()
Returns the set of permission strings the user_obj has from the
permissions of the groups they belong. Returns an empty set if
is_anonymous or
is_active is False.
Changed in Django 5.2: aget_group_permissions() function was added.
aget_all_permissions(user_obj, obj=None)
Asynchronous version: aget_all_permissions()
Returns the set of permission strings the user_obj has, including both
user permissions and group permissions. Returns an empty set if
is_anonymous or
is_active is False.
Changed in Django 5.2: aget_all_permissions() function was added.
ahas_perm(user_obj, perm, obj=None)
Asynchronous version: ahas_perm()
Uses get_all_permissions() to check if user_obj has the
permission string perm. Returns False if the user is not
is_active.
Changed in Django 5.2: ahas_perm() function was added.
ahas_module_perms(user_obj, app_label)
Asynchronous version: ahas_module_perms()
Returns whether the user_obj has any permissions on the app
app_label.
Changed in Django 5.2: ahas_module_perms() function was added.
user_can_authenticate()[source]
Returns whether the user is allowed to authenticate. To match the
behavior of AuthenticationForm
which prohibits inactive users from logging in,
this method returns False for users with is_active=False. Custom user models that
don’t have an is_active
field are allowed.
with_perm(perm, is_active=True, include_superusers=True, obj=None)[source]
Returns all active users who have the permission perm either in
the form of "<app label>.<permission codename>" or a
Permission instance. Returns an
empty queryset if no users who have the perm found.
If is_active is True (default), returns only active users, or
if False, returns only inactive users. Use None to return all
users irrespective of active state.
If include_superusers is True (default), the result will
include superusers.
class AllowAllUsersModelBackend[source]
Same as ModelBackend except that it doesn’t reject inactive users
because user_can_authenticate() always returns True.
When using this backend, you’ll likely want to customize the
AuthenticationForm used by the
LoginView by overriding the
confirm_login_allowed()
method as it rejects inactive users.
class RemoteUserBackend[source]
Use this backend to take advantage of external-to-Django-handled
authentication. It authenticates using usernames passed in
request.META['REMOTE_USER']. See
the Authenticating against REMOTE_USER
documentation.
If you need more control, you can create your own authentication backend
that inherits from this class and override these attributes or methods:
create_unknown_user
True or False. Determines whether or not a user object is
created if not already in the database Defaults to True.
aauthenticate(request, remote_user)
Asynchronous version: aauthenticate()
The username passed as remote_user is considered trusted. This
method returns the user object with the given username, creating a new
user object if create_unknown_user is
True.
Returns None if create_unknown_user is
False and a User object with the given username is not found in
the database.
request is an HttpRequest and may be None
if it wasn’t provided to authenticate()
(which passes it on to the backend).
Changed in Django 5.2: aauthenticate() function was added.
clean_username(username)[source]
Performs any cleaning on the username (e.g. stripping LDAP DN
information) prior to using it to get or create a user object. Returns
the cleaned username.
aconfigure_user(request, user, created=True)
Asynchronous version: aconfigure_user()
Configures the user on each authentication attempt. This method is
called immediately after fetching or creating the user being
authenticated, and can be used to perform custom setup actions, such as
setting the user’s groups based on attributes in an LDAP directory.
Returns the user object. When fetching or creating an user is called
from a synchronous context, configure_user is called,
aconfigure_user is called from async contexts.
The setup can be performed either once when the user is created
(created is True) or on existing users (created is
False) as a way of synchronizing attributes between the remote and
the local systems.
request is an HttpRequest and may be None
if it wasn’t provided to authenticate()
(which passes it on to the backend).
Changed in Django 5.2: aconfigure_user() function was added.
user_can_authenticate()
Returns whether the user is allowed to authenticate. This method
returns False for users with is_active=False. Custom user models that
don’t have an is_active
field are allowed.
class AllowAllUsersRemoteUserBackend[source]
Same as RemoteUserBackend except that it doesn’t reject inactive
users because user_can_authenticate always
returns True.
aget_user(request)
Asynchronous version: aget_user()
Returns the user model instance associated with the given request’s
session.
It checks if the authentication backend stored in the session is present in
AUTHENTICATION_BACKENDS. If so, it uses the backend’s
get_user() method to retrieve the user model instance and then verifies
the session by calling the user model’s
get_session_auth_hash()
method. If the verification fails and SECRET_KEY_FALLBACKS are
provided, it verifies the session against each fallback key using
get_session_auth_fallback_hash().
Returns an instance of AnonymousUser
if the authentication backend stored in the session is no longer in
AUTHENTICATION_BACKENDS, if a user isn’t returned by the
backend’s get_user() method, or if the session auth hash doesn’t
validate.
Try the FAQ — it's got answers to many common questions.
Index, Module Index, or Table of Contents
Handy when looking for specific information.
Django Discord Server
Join the Django Discord Community.
Official Django Forum
Join the community on the Django Forum.
Ticket tracker
Report bugs with Django or Django documentation in our ticket tracker.
