The authentication that comes with Django is good enough for most common cases,but you may have needs not met by the out-of-the-box defaults. Customizingauthentication in your projects requires understanding what points of theprovided system are extensible or replaceable. This document provides detailsabout how the auth system can be customized.
Authentication backends provide an extensiblesystem for when a username and password stored with the user model need to beauthenticated against a different service than Django’s default.
You can give your models custom permissions thatcan be checked through Django’s authorization system.
You can extend the default User
model, orsubstitute a completely customized model.
Other authentication sources¶
There may be times you have the need to hook into another authentication source– that is, another source of usernames and passwords or authenticationmethods.
For example, your company may already have an LDAP setup that stores a usernameand password for every employee. It’d be a hassle for both the networkadministrator and the users themselves if users had separate accounts in LDAPand the Django-based applications.
So, to handle situations like this, the Django authentication system lets youplug in other authentication sources. You can override Django’s defaultdatabase-based scheme, or you can use the default system in tandem with othersystems.
See the authentication backend reference for information on the authenticationbackends included with Django.
Specifying authentication backends¶
Behind the scenes, Django maintains a list of “authentication backends” that itchecks for authentication. When somebody callsdjango.contrib.auth.authenticate() – as described in How to loga user in – Django tries authenticating acrossall of its authentication backends. If the first authentication method fails,Django tries the second one, and so on, until all backends have been attempted.
The list of authentication backends to use is specified in theAUTHENTICATION_BACKENDS setting. This should be a list of Pythonpath names that point to Python classes that know how to authenticate. Theseclasses can be anywhere on your Python path.
By default, AUTHENTICATION_BACKENDS is set to:
["django.contrib.auth.backends.ModelBackend"]
That’s the basic authentication backend that checks the Django users databaseand queries the built-in permissions. It does not provide protection againstbrute force attacks via any rate limiting mechanism. You may either implementyour own rate limiting mechanism in a custom auth backend, or use themechanisms provided by most web servers.
The order of AUTHENTICATION_BACKENDS matters, so if the sameusername and password is valid in multiple backends, Django will stopprocessing at the first positive match.
If a backend raises a PermissionDeniedexception, authentication will immediately fail. Django won’t check thebackends that follow.
Note
Once a user has authenticated, Django stores which backend was used toauthenticate the user in the user’s session, and reuses the same backendfor the duration of that session whenever access to the currentlyauthenticated user is needed. This effectively means that authenticationsources are cached on a per-session basis, so if you changeAUTHENTICATION_BACKENDS, you’ll need to clear out session data ifyou need to force users to re-authenticate using different methods. Asimple way to do that is to execute Session.objects.all().delete()
.
Writing an authentication backend¶
An authentication backend is a class that implements two required methods:get_user(user_id)
and authenticate(request, **credentials)
, as well asa set of optional permission related authorization methods.
The get_user
method takes a user_id
– which could be a username,database ID or whatever, but has to be the primary key of your user object –and returns a user object or None
.
The authenticate
method takes a request
argument and credentials askeyword arguments. Most of the time, it’ll look like this:
from django.contrib.auth.backends import BaseBackendclass MyBackend(BaseBackend): def authenticate(self, request, username=None, password=None): # Check the username/password and return a user. ...
But it could also authenticate a token, like so:
from django.contrib.auth.backends import BaseBackendclass MyBackend(BaseBackend): def authenticate(self, request, token=None): # Check the token and return a user. ...
Either way, authenticate()
should check the credentials it gets and returna user object that matches those credentials if the credentials are valid. Ifthey’re not valid, it should return None
.
request
is an HttpRequest and may be None
if itwasn’t provided to authenticate() (which passes iton to the backend).
The Django admin is tightly coupled to the Django User object. The best way to deal with this is to create a Django User
object for each user that exists for your backend (e.g., in your LDAPdirectory, your external SQL database, etc.) You can either write a script todo this in advance, or your authenticate
method can do it the first time auser logs in.
Here’s an example backend that authenticates against a username and passwordvariable defined in your settings.py
file and creates a Django User
object the first time a user authenticates:
from django.conf import settingsfrom django.contrib.auth.backends import BaseBackendfrom django.contrib.auth.hashers import check_passwordfrom django.contrib.auth.models import Userclass SettingsBackend(BaseBackend): """ Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD. Use the login name and a hash of the password. For example: ADMIN_LOGIN = 'admin' ADMIN_PASSWORD = 'pbkdf2_sha256$30000$Vo0VlMnkR4Bk$qEvtdyZRWTcOsCnI/oQ7fVOu1XAURIZYoOZ3iq8Dr4M=' """ def authenticate(self, request, username=None, password=None): login_valid = settings.ADMIN_LOGIN == username pwd_valid = check_password(password, settings.ADMIN_PASSWORD) if login_valid and pwd_valid: try: user = User.objects.get(username=username) except User.DoesNotExist: # Create a new user. There's no need to set a password # because only the password from settings.py is checked. user = User(username=username) user.is_staff = True user.is_superuser = True user.save() return user return None def get_user(self, user_id): try: return User.objects.get(pk=user_id) except User.DoesNotExist: return None
Handling authorization in custom backends¶
Custom auth backends can provide their own permissions.
The user model and its manager will delegate permission lookup functions(get_user_permissions(),get_group_permissions(),get_all_permissions(),has_perm(),has_module_perms(), andwith_perm()) to anyauthentication backend that implements these functions.
The permissions given to the user will be the superset of all permissionsreturned by all backends. That is, Django grants a permission to a user thatany one backend grants.
If a backend raises a PermissionDeniedexception in has_perm() orhas_module_perms(), the authorizationwill immediately fail and Django won’t check the backends that follow.
A backend could implement permissions for the magic admin like this:
from django.contrib.auth.backends import BaseBackendclass MagicAdminBackend(BaseBackend): def has_perm(self, user_obj, perm, obj=None): return user_obj.username == settings.ADMIN_LOGIN
This gives full permissions to the user granted access in the above example.Notice that in addition to the same arguments given to the associateddjango.contrib.auth.models.User functions, the backend auth functionsall take the user object, which may be an anonymous user, as an argument.
A full authorization implementation can be found in the ModelBackend
classin django/contrib/auth/backends.py, which is the default backend andqueries the auth_permission
table most of the time.
Authorization for anonymous users¶
An anonymous user is one that is not authenticated i.e. they have provided novalid authentication details. However, that does not necessarily mean they arenot authorized to do anything. At the most basic level, most websitesauthorize anonymous users to browse most of the site, and many allow anonymousposting of comments etc.
Django’s permission framework does not have a place to store permissions foranonymous users. However, the user object passed to an authentication backendmay be an django.contrib.auth.models.AnonymousUser object, allowingthe backend to specify custom authorization behavior for anonymous users. Thisis especially useful for the authors of reusable apps, who can delegate allquestions of authorization to the auth backend, rather than needing settings,for example, to control anonymous access.
Authorization for inactive users¶
An inactive user is one that has itsis_active field set to False
. TheModelBackend andRemoteUserBackend authenticationbackends prohibits these users from authenticating. If a custom user modeldoesn’t have an is_active field,all users will be allowed to authenticate.
You can use AllowAllUsersModelBackendor AllowAllUsersRemoteUserBackend if youwant to allow inactive users to authenticate.
The support for anonymous users in the permission system allows for a scenariowhere anonymous users have permissions to do something while inactiveauthenticated users do not.
Do not forget to test for the is_active
attribute of the user in your ownbackend permission methods.
Handling object permissions¶
Django’s permission framework has a foundation for object permissions, thoughthere is no implementation for it in the core. That means that checking forobject permissions will always return False
or an empty list (depending onthe check performed). An authentication backend will receive the keywordparameters obj
and user_obj
for each object related authorizationmethod and can return the object level permission as appropriate.
Custom permissions¶
To create custom permissions for a given model object, use the permissions
model Meta attribute.
This example Task
model creates two custom permissions, i.e., actions userscan or cannot do with Task
instances, specific to your application:
class Task(models.Model): ... class Meta: permissions = [ ("change_task_status", "Can change the status of tasks"), ("close_task", "Can remove a task by setting its status as closed"), ]
The only thing this does is create those extra permissions when you runmanage.py migrate (the function that creates permissionsis connected to the post_migrate signal).Your code is in charge of checking the value of these permissions when a useris trying to access the functionality provided by the application (changing thestatus of tasks or closing tasks.) Continuing the above example, the followingchecks if a user may close tasks:
user.has_perm("app.close_task")
Extending the existing User
model¶
There are two ways to extend the defaultUser model without substituting your ownmodel. If the changes you need are purely behavioral, and don’t require anychange to what is stored in the database, you can create a proxy model based on User. Thisallows for any of the features offered by proxy models including defaultordering, custom managers, or custom model methods.
If you wish to store information related to User
, you can use aOneToOneField to a model containing the fields foradditional information. This one-to-one model is often called a profile model,as it might store non-auth related information about a site user. For exampleyou might create an Employee model:
from django.contrib.auth.models import Userclass Employee(models.Model): user = models.OneToOneField(User, on_delete=models.CASCADE) department = models.CharField(max_length=100)
Assuming an existing Employee Fred Smith who has both a User and Employeemodel, you can access the related information using Django’s standard relatedmodel conventions:
>>> u = User.objects.get(username="fsmith")>>> freds_department = u.employee.department
To add a profile model’s fields to the user page in the admin, define anInlineModelAdmin (for this example, we’ll use aStackedInline) in your app’s admin.py
andadd it to a UserAdmin
class which is registered with theUser class:
from django.contrib import adminfrom django.contrib.auth.admin import UserAdmin as BaseUserAdminfrom django.contrib.auth.models import Userfrom my_user_profile_app.models import Employee# Define an inline admin descriptor for Employee model# which acts a bit like a singletonclass EmployeeInline(admin.StackedInline): model = Employee can_delete = False verbose_name_plural = "employee"# Define a new User adminclass UserAdmin(BaseUserAdmin): inlines = [EmployeeInline]# Re-register UserAdminadmin.site.unregister(User)admin.site.register(User, UserAdmin)
These profile models are not special in any way - they are just Django modelsthat happen to have a one-to-one link with a user model. As such, they aren’tauto created when a user is created, buta django.db.models.signals.post_save could be used to create or updaterelated models as appropriate.
Using related models results in additional queries or joins to retrieve therelated data. Depending on your needs, a custom user model that includes therelated fields may be your better option, however, existing relations to thedefault user model within your project’s apps may justify the extra databaseload.
Substituting a custom User
model¶
Some kinds of projects may have authentication requirements for which Django’sbuilt-in User model is not alwaysappropriate. For instance, on some sites it makes more sense to use an emailaddress as your identification token instead of a username.
Django allows you to override the default user model by providing a value forthe AUTH_USER_MODEL setting that references a custom model:
AUTH_USER_MODEL = "myapp.MyUser"
This dotted pair describes the label of theDjango app (which must be in your INSTALLED_APPS), and the name ofthe Django model that you wish to use as your user model.
Using a custom user model when starting a project¶
If you’re starting a new project, it’s highly recommended to set up a customuser model, even if the default User modelis sufficient for you. This model behaves identically to the default usermodel, but you’ll be able to customize it in the future if the need arises:
from django.contrib.auth.models import AbstractUserclass User(AbstractUser): pass
Don’t forget to point AUTH_USER_MODEL to it. Do this before creatingany migrations or running manage.py migrate
for the first time.
Also, register the model in the app’s admin.py
:
from django.contrib import adminfrom django.contrib.auth.admin import UserAdminfrom .models import Useradmin.site.register(User, UserAdmin)
Changing to a custom user model mid-project¶
Changing AUTH_USER_MODEL after you’ve created database tables issignificantly more difficult since it affects foreign keys and many-to-manyrelationships, for example.
This change can’t be done automatically and requires manually fixing yourschema, moving your data from the old user table, and possibly manuallyreapplying some migrations. See #25313 for an outline of the steps.
Due to limitations of Django’s dynamic dependency feature for swappablemodels, the model referenced by AUTH_USER_MODEL must be created inthe first migration of its app (usually called 0001_initial
); otherwise,you’ll have dependency issues.
In addition, you may run into a CircularDependencyError
when running yourmigrations as Django won’t be able to automatically break the dependency loopdue to the dynamic dependency. If you see this error, you should break the loopby moving the models depended on by your user model into a second migration.(You can try making two normal models that have a ForeignKey
to each otherand seeing how makemigrations
resolves that circular dependency if you wantto see how it’s usually done.)
Reusable apps and AUTH_USER_MODEL
¶
Reusable apps shouldn’t implement a custom user model. A project may use manyapps, and two reusable apps that implemented a custom user model couldn’t beused together. If you need to store per user information in your app, usea ForeignKey orOneToOneField to settings.AUTH_USER_MODEL
as described below.
Referencing the User
model¶
If you reference User directly (forexample, by referring to it in a foreign key), your code will not work inprojects where the AUTH_USER_MODEL setting has been changed to adifferent user model.
get_user_model
()[source]¶Instead of referring to User directly,you should reference the user model using
django.contrib.auth.get_user_model()
. This method will return thecurrently active user model – the custom user model if one is specified, orUser otherwise.When you define a foreign key or many-to-many relations to the user model,you should specify the custom model using the AUTH_USER_MODELsetting. For example:
from django.conf import settingsfrom django.db import modelsclass Article(models.Model): author = models.ForeignKey( settings.AUTH_USER_MODEL, on_delete=models.CASCADE, )
When connecting to signals sent by the user model, you should specifythe custom model using the AUTH_USER_MODEL setting. For example:
from django.conf import settingsfrom django.db.models.signals import post_savedef post_save_receiver(sender, instance, created, **kwargs): passpost_save.connect(post_save_receiver, sender=settings.AUTH_USER_MODEL)
Generally speaking, it’s easiest to refer to the user model with theAUTH_USER_MODEL setting in code that’s executed at import time,however, it’s also possible to call
get_user_model()
while Djangois importing models, so you could usemodels.ForeignKey(get_user_model(), ...)
.If your app is tested with multiple user models, using
@override_settings(AUTH_USER_MODEL=...)
for example, and you cache theresult ofget_user_model()
in a module-level variable, you may need tolisten to the setting_changed signal to clearthe cache. For example:from django.apps import appsfrom django.contrib.auth import get_user_modelfrom django.core.signals import setting_changedfrom django.dispatch import receiver@receiver(setting_changed)def user_model_swapped(*, setting, **kwargs): if setting == "AUTH_USER_MODEL": apps.clear_cache() from myapp import some_module some_module.UserModel = get_user_model()
Specifying a custom user model¶
When you start your project with a custom user model, stop to consider if thisis the right choice for your project.
Keeping all user related information in one model removes the need foradditional or more complex database queries to retrieve related models. On theother hand, it may be more suitable to store app-specific user information in amodel that has a relation with your custom user model. That allows each app tospecify its own user data requirements without potentially conflicting orbreaking assumptions by other apps. It also means that you would keep your usermodel as simple as possible, focused on authentication, and following theminimum requirements Django expects custom user models to meet.
If you use the default authentication backend, then your model must have asingle unique field that can be used for identification purposes. This canbe a username, an email address, or any other unique attribute. A non-uniqueusername field is allowed if you use a custom authentication backend thatcan support it.
The easiest way to construct a compliant custom user model is to inherit fromAbstractBaseUser.AbstractBaseUser provides the coreimplementation of a user model, including hashed passwords and tokenizedpassword resets. You must then provide some key implementation details:
- class
models.
CustomUser
¶ USERNAME_FIELD
¶A string describing the name of the field on the user model that isused as the unique identifier. This will usually be a username of somekind, but it can also be an email address, or any other uniqueidentifier. The field must be unique (e.g. have
unique=True
setin its definition), unless you use a custom authentication backend thatcan support non-unique usernames.In the following example, the field
identifier
is usedas the identifying field:class MyUser(AbstractBaseUser): identifier = models.CharField(max_length=40, unique=True) ... USERNAME_FIELD = "identifier"
EMAIL_FIELD
¶A string describing the name of the email field on the
User
model.This value is returned byget_email_field_name().
REQUIRED_FIELDS
¶A list of the field names that will be prompted for when creating auser via the createsuperuser management command. The userwill be prompted to supply a value for each of these fields. It mustinclude any field for which blank is
False
or undefined and may include additional fields you wantprompted for when a user is created interactively.REQUIRED_FIELDS
has no effect in other parts of Django, likecreating a user in the admin.For example, here is the partial definition for a user model thatdefines two required fields - a date of birth and height:
class MyUser(AbstractBaseUser): ... date_of_birth = models.DateField() height = models.FloatField() ... REQUIRED_FIELDS = ["date_of_birth", "height"]
Note
REQUIRED_FIELDS
must contain all required fields on your usermodel, but should not contain theUSERNAME_FIELD
orpassword
as these fields will always be prompted for.
is_active
¶A boolean attribute that indicates whether the user is considered“active”. This attribute is provided as an attribute on
AbstractBaseUser
defaulting toTrue
. How you choose toimplement it will depend on the details of your chosen auth backends.See the documentation of the is_active attribute on the built-inuser model for details.
get_full_name
()¶Optional. A longer formal identifier for the user such as their fullname. If implemented, this appears alongside the username in anobject’s history in django.contrib.admin.
get_short_name
()¶Optional. A short, informal identifier for the user such as theirfirst name. If implemented, this replaces the username in the greetingto the user in the header of django.contrib.admin.
Importing
AbstractBaseUser
AbstractBaseUser
andBaseUserManager
are importable fromdjango.contrib.auth.base_user
so that they can be imported withoutincludingdjango.contrib.auth
in INSTALLED_APPS.
The following attributes and methods are available on any subclass ofAbstractBaseUser:
- class
models.
AbstractBaseUser
¶ get_username
()¶Returns the value of the field nominated by
USERNAME_FIELD
.
clean
()¶Normalizes the username by calling normalize_username(). If youoverride this method, be sure to call
super()
to retain thenormalization.
- classmethod
get_email_field_name
()¶ Returns the name of the email field specified by theEMAIL_FIELD attribute. Defaults to
'email'
ifEMAIL_FIELD
isn’t specified.
- classmethod
normalize_username
(username)¶ Applies NFKC Unicode normalization to usernames so that visuallyidentical characters with different Unicode code points are consideredidentical.
is_authenticated
¶Read-only attribute which is always
True
(as opposed toAnonymousUser.is_authenticated
which is alwaysFalse
).This is a way to tell if the user has been authenticated. This does notimply any permissions and doesn’t check if the user is active or hasa valid session. Even though normally you will check this attribute onrequest.user
to find out whether it has been populated by theAuthenticationMiddleware(representing the currently logged-in user), you should know thisattribute isTrue
for any User instance.
is_anonymous
¶Read-only attribute which is always
False
. This is a way ofdifferentiating User and AnonymousUserobjects. Generally, you should prefer usingis_authenticated to this attribute.
set_password
(raw_password)¶Sets the user’s password to the given raw string, taking care of thepassword hashing. Doesn’t save theAbstractBaseUser object.
When the raw_password is
None
, the password will be set to anunusable password, as ifset_unusable_password()were used.
check_password
(raw_password)¶
acheck_password
(raw_password)¶Asynchronous version:
acheck_password()
Returns
True
if the given raw string is the correct password forthe user. (This takes care of the password hashing in making thecomparison.)Changed in Django 5.0:
acheck_password()
method was added.
set_unusable_password
()¶Marks the user as having no password set. This isn’t the same ashaving a blank string for a password.check_password() for this userwill never return
True
. Doesn’t save theAbstractBaseUser object.You may need this if authentication for your application takes placeagainst an existing external source such as an LDAP directory.
has_usable_password
()¶Returns
False
ifset_unusable_password() hasbeen called for this user.
get_session_auth_hash
()¶Returns an HMAC of the password field. Used forSession invalidation on password change.
get_session_auth_fallback_hash
()¶Yields the HMAC of the password field usingSECRET_KEY_FALLBACKS. Used by
get_user()
.
AbstractUser subclasses AbstractBaseUser:
- class
models.
AbstractUser
¶ clean
()¶Normalizes the email by callingBaseUserManager.normalize_email(). If you override this method,be sure to call
super()
to retain the normalization.
Writing a manager for a custom user model¶
You should also define a custom manager for your user model. If your user modeldefines username
, email
, is_staff
, is_active
, is_superuser
,last_login
, and date_joined
fields the same as Django’s default user,you can install Django’s UserManager;however, if your user model defines different fields, you’ll need to define acustom manager that extends BaseUserManagerproviding two additional methods:
- class
models.
CustomUserManager
¶ create_user
(username_field, password=None, **other_fields)¶The prototype of
create_user()
should accept the username field,plus all required fields as arguments. For example, if your user modelusesemail
as the username field, and hasdate_of_birth
as arequired field, thencreate_user
should be defined as:def create_user(self, email, date_of_birth, password=None): # create user here ...
create_superuser
(username_field, password=None, **other_fields)¶The prototype of
create_superuser()
should accept the usernamefield, plus all required fields as arguments. For example, if your usermodel usesemail
as the username field, and hasdate_of_birth
as a required field, thencreate_superuser
should be defined as:def create_superuser(self, email, date_of_birth, password=None): # create superuser here ...
For a ForeignKey in USERNAME_FIELD orREQUIRED_FIELDS, these methods receive the value of theto_field (the primary_keyby default) of an existing instance.
BaseUserManager provides the followingutility methods:
- class
models.
BaseUserManager
¶ - classmethod
normalize_email
(email)¶ Normalizes email addresses by lowercasing the domain portion of theemail address.
get_by_natural_key
(username)¶Retrieves a user instance using the contents of the fieldnominated by
USERNAME_FIELD
.
- classmethod
Extending Django’s default User
¶
If you’re entirely happy with Django’s Usermodel, but you want to add some additional profile information, you couldsubclass django.contrib.auth.models.AbstractUser and add your customprofile fields, although we’d recommend a separate model as described inSpecifying a custom user model. AbstractUser
provides the fullimplementation of the default User as anabstract model.
Custom users and the built-in auth forms¶
Django’s built-in forms and views make certain assumptions about the user model that theyare working with.
The following forms are compatible with any subclass ofAbstractBaseUser:
- AuthenticationForm: Uses the usernamefield specified by USERNAME_FIELD.
- SetPasswordForm
- PasswordChangeForm
- AdminPasswordChangeForm
The following forms make assumptions about the user model and can be used as-isif those assumptions are met:
- PasswordResetForm: Assumes that the usermodel has a field that stores the user’s email address with the name returnedby get_email_field_name() (
email
bydefault) that can be used to identify the user and a boolean field namedis_active
to prevent password resets for inactive users.
Finally, the following forms are tied toUser and need to be rewritten or extendedto work with a custom user model:
- UserCreationForm
- UserChangeForm
If your custom user model is a subclass of AbstractUser
, then you canextend these forms in this manner:
from django.contrib.auth.forms import UserCreationFormfrom myapp.models import CustomUserclass CustomUserCreationForm(UserCreationForm): class Meta(UserCreationForm.Meta): model = CustomUser fields = UserCreationForm.Meta.fields + ("custom_field",)
Custom users and django.contrib.admin¶
If you want your custom user model to also work with the admin, your user modelmust define some additional attributes and methods. These methods allow theadmin to control access of the user to admin content:
- class
models.
CustomUser
is_staff
¶Returns
True
if the user is allowed to have access to the admin site.
is_active
¶Returns
True
if the user account is currently active.
has_perm(perm, obj=None):
Returns
True
if the user has the named permission. Ifobj
isprovided, the permission needs to be checked against a specific objectinstance.
has_module_perms(app_label):
Returns
True
if the user has permission to access models inthe given app.
You will also need to register your custom user model with the admin. Ifyour custom user model extends django.contrib.auth.models.AbstractUser
,you can use Django’s existing django.contrib.auth.admin.UserAdmin
class. However, if your user model extendsAbstractBaseUser, you’ll need to definea custom ModelAdmin
class. It may be possible to subclass the defaultdjango.contrib.auth.admin.UserAdmin
; however, you’ll need tooverride any of the definitions that refer to fields ondjango.contrib.auth.models.AbstractUser
that aren’t on yourcustom user class.
Note
If you are using a custom ModelAdmin
which is a subclass ofdjango.contrib.auth.admin.UserAdmin
, then you need to add your customfields to fieldsets
(for fields to be used in editing users) and toadd_fieldsets
(for fields to be used when creating a user). Forexample:
from django.contrib.auth.admin import UserAdminclass CustomUserAdmin(UserAdmin): ... fieldsets = UserAdmin.fieldsets + ((None, {"fields": ["custom_field"]}),) add_fieldsets = UserAdmin.add_fieldsets + ((None, {"fields": ["custom_field"]}),)
See a full example for moredetails.
Custom users and permissions¶
To make it easy to include Django’s permission framework into your own userclass, Django provides PermissionsMixin.This is an abstract model you can include in the class hierarchy for your usermodel, giving you all the methods and database fields necessary to supportDjango’s permission model.
PermissionsMixin provides the followingmethods and attributes:
- class
models.
PermissionsMixin
¶ is_superuser
¶Boolean. Designates that this user has all permissions withoutexplicitly assigning them.
get_user_permissions
(obj=None)¶Returns a set of permission strings that the user has directly.
If
obj
is passed in, only returns the user permissions for thisspecific object.
get_group_permissions
(obj=None)¶Returns a set of permission strings that the user has, through theirgroups.
If
obj
is passed in, only returns the group permissions forthis specific object.
get_all_permissions
(obj=None)¶Returns a set of permission strings that the user has, both throughgroup and user permissions.
If
obj
is passed in, only returns the permissions for thisspecific object.
has_perm
(perm, obj=None)¶Returns
True
if the user has the specified permission, whereperm
is in the format"<app label>.<permission codename>"
(seepermissions). If User.is_activeand is_superuser are bothTrue
, this method alwaysreturnsTrue
.If
obj
is passed in, this method won’t check for a permission forthe model, but for this specific object.
has_perms
(perm_list, obj=None)¶Returns
True
if the user has each of the specified permissions,where each perm is in the format"<app label>.<permission codename>"
. If User.is_active andis_superuser are bothTrue
, this method alwaysreturnsTrue
.If
obj
is passed in, this method won’t check for permissions forthe model, but for the specific object.
has_module_perms
(package_name)¶Returns
True
if the user has any permissions in the given package(the Django app label). If User.is_active andis_superuser are bothTrue
, this method alwaysreturnsTrue
.
PermissionsMixin
and ModelBackend
If you don’t include thePermissionsMixin, you must ensure youdon’t invoke the permissions methods on ModelBackend
. ModelBackend
assumes that certain fields are available on your user model. If your usermodel doesn’t provide those fields, you’ll receive database errors whenyou check permissions.
Custom users and proxy models¶
One limitation of custom user models is that installing a custom user modelwill break any proxy model extending User.Proxy models must be based on a concrete base class; by defining a custom usermodel, you remove the ability of Django to reliably identify the base class.
If your project uses proxy models, you must either modify the proxy to extendthe user model that’s in use in your project, or merge your proxy’s behaviorinto your User subclass.
A full example¶
Here is an example of an admin-compliant custom user app. This user model usesan email address as the username, and has a required date of birth; itprovides no permission checking beyond an admin
flag on the user account.This model would be compatible with all the built-in auth forms and views,except for the user creation forms. This example illustrates how most of thecomponents work together, but is not intended to be copied directly intoprojects for production use.
This code would all live in a models.py
file for a customauthentication app:
from django.db import modelsfrom django.contrib.auth.models import BaseUserManager, AbstractBaseUserclass MyUserManager(BaseUserManager): def create_user(self, email, date_of_birth, password=None): """ Creates and saves a User with the given email, date of birth and password. """ if not email: raise ValueError("Users must have an email address") user = self.model( email=self.normalize_email(email), date_of_birth=date_of_birth, ) user.set_password(password) user.save(using=self._db) return user def create_superuser(self, email, date_of_birth, password=None): """ Creates and saves a superuser with the given email, date of birth and password. """ user = self.create_user( email, password=password, date_of_birth=date_of_birth, ) user.is_admin = True user.save(using=self._db) return userclass MyUser(AbstractBaseUser): email = models.EmailField( verbose_name="email address", max_length=255, unique=True, ) date_of_birth = models.DateField() is_active = models.BooleanField(default=True) is_admin = models.BooleanField(default=False) objects = MyUserManager() USERNAME_FIELD = "email" REQUIRED_FIELDS = ["date_of_birth"] def __str__(self): return self.email def has_perm(self, perm, obj=None): "Does the user have a specific permission?" # Simplest possible answer: Yes, always return True def has_module_perms(self, app_label): "Does the user have permissions to view the app `app_label`?" # Simplest possible answer: Yes, always return True @property def is_staff(self): "Is the user a member of staff?" # Simplest possible answer: All admins are staff return self.is_admin
Then, to register this custom user model with Django’s admin, the followingcode would be required in the app’s admin.py
file:
from django import formsfrom django.contrib import adminfrom django.contrib.auth.models import Groupfrom django.contrib.auth.admin import UserAdmin as BaseUserAdminfrom django.contrib.auth.forms import ReadOnlyPasswordHashFieldfrom django.core.exceptions import ValidationErrorfrom customauth.models import MyUserclass UserCreationForm(forms.ModelForm): """A form for creating new users. Includes all the required fields, plus a repeated password.""" password1 = forms.CharField(label="Password", widget=forms.PasswordInput) password2 = forms.CharField( label="Password confirmation", widget=forms.PasswordInput ) class Meta: model = MyUser fields = ["email", "date_of_birth"] def clean_password2(self): # Check that the two password entries match password1 = self.cleaned_data.get("password1") password2 = self.cleaned_data.get("password2") if password1 and password2 and password1 != password2: raise ValidationError("Passwords don't match") return password2 def save(self, commit=True): # Save the provided password in hashed format user = super().save(commit=False) user.set_password(self.cleaned_data["password1"]) if commit: user.save() return userclass UserChangeForm(forms.ModelForm): """A form for updating users. Includes all the fields on the user, but replaces the password field with admin's disabled password hash display field. """ password = ReadOnlyPasswordHashField() class Meta: model = MyUser fields = ["email", "password", "date_of_birth", "is_active", "is_admin"]class UserAdmin(BaseUserAdmin): # The forms to add and change user instances form = UserChangeForm add_form = UserCreationForm # The fields to be used in displaying the User model. # These override the definitions on the base UserAdmin # that reference specific fields on auth.User. list_display = ["email", "date_of_birth", "is_admin"] list_filter = ["is_admin"] fieldsets = [ (None, {"fields": ["email", "password"]}), ("Personal info", {"fields": ["date_of_birth"]}), ("Permissions", {"fields": ["is_admin"]}), ] # add_fieldsets is not a standard ModelAdmin attribute. UserAdmin # overrides get_fieldsets to use this attribute when creating a user. add_fieldsets = [ ( None, { "classes": ["wide"], "fields": ["email", "date_of_birth", "password1", "password2"], }, ), ] search_fields = ["email"] ordering = ["email"] filter_horizontal = []# Now register the new UserAdmin...admin.site.register(MyUser, UserAdmin)# ... and, since we're not using Django's built-in permissions,# unregister the Group model from admin.admin.site.unregister(Group)
Finally, specify the custom model as the default user model for your projectusing the AUTH_USER_MODEL setting in your settings.py
:
AUTH_USER_MODEL = "customauth.MyUser"