Customizing authentication in Django | Django documentation (2024)

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 Userobject 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 Userobject 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 permissionsmodel 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_MODELas 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 usingdjango.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 of get_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 isFalse 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 the USERNAME_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 onAbstractBaseUser defaulting to True. 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 and BaseUserManager are importable fromdjango.contrib.auth.base_user so that they can be imported withoutincluding django.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' if EMAIL_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 always False).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 is True 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 modeluses email as the username field, and has date_of_birth as arequired field, then create_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 uses email as the username field, and has date_of_birthas a required field, then create_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.

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. If obj 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.UserAdminclass. 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 both True, this method alwaysreturns True.

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 both True, this method alwaysreturns True.

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 both True, this method alwaysreturns True.

PermissionsMixin and ModelBackend

If you don’t include thePermissionsMixin, you must ensure youdon’t invoke the permissions methods on ModelBackend. ModelBackendassumes 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"
Customizing authentication in Django | Django documentation (2024)

FAQs

How to implement custom authentication in Django? ›

backends import BaseBackend class 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 return a user object that matches those credentials if the credentials are valid.

How to make authentication with Django? ›

User Authentication System in Django

html” template when the user accesses the home page of the application. login_page(request): This function handles user login. If the HTTP request method is POST (i.e., the user is submitting a login form), it retrieves the entered username and password from the POST data.

How to change password in Django documentation? ›

To change a user's password, you have several options: manage.py changepassword *username* offers a method of changing a user's password from the command line. It prompts you to change the password of a given user which you must enter twice. If they both match, the new password will be changed immediately.

How do I manually authenticate a user in Django? ›

Authenticating users¶

Use authenticate() to verify a set of credentials. It takes credentials as keyword arguments, username and password for the default case, checks them against each authentication backend, and returns a User object if the credentials are valid for a backend.

What is the best authentication package for Django? ›

Django-allauth

You can use Django-allauth, which is one of the most useful Django packages if you want to create an application that requires strong and multiple authentication systems. Django-allauth provides ways to authenticate users via local and social authentication systems.

What is the difference between authentication and authorization in Django? ›

The Django authentication system handles both authentication and authorization. Briefly, authentication verifies a user is who they claim to be, and authorization determines what an authenticated user is allowed to do. Here the term authentication is used to refer to both tasks.

How many types of authentication are there in Django? ›

Django's built-in authentication system includes permissions, users, and groups. Django automatically creates four default permissions when you create a model—add, delete, change, and view. These permissions allow users to add, delete, modify, or view instances of the model respectively.

Does Django have built-in authentication? ›

Django provides an authentication and authorization ("permission") system, built on top of the session framework discussed in the previous tutorial, that allows you to verify user credentials and define what actions each user is allowed to perform.

Does Django use basic authentication? ›

This authentication scheme uses HTTP Basic Authentication, signed against a user's username and password. Basic authentication is generally only appropriate for testing. If successfully authenticated, BasicAuthentication provides the following credentials. request.user will be a Django User instance.

How to customize admin login in Django? ›

You can fully customize the admin by changing the templates used to render pages. The Django template engine has a defined order for loading templates. When it loads a template, it uses the first template that matches the name. You can override admin templates by using the same directory structure and file names.

How to set username and password in Django? ›

This is done by typing this command in the command view:
  1. py manage.py createsuperuser.
  2. Username:
  3. Username: johndoe. Email address: johndoe@dummymail.com. Password: Password (again): ...
  4. Bypass password validation and create user anyway? [ y/N]: y.
  5. Superuser created successfully.
  6. py manage.py runserver.

How to handle passwords in Django? ›

For storing passwords, Django will use the first hasher in PASSWORD_HASHERS . To store new passwords with a different algorithm, put your preferred algorithm first in PASSWORD_HASHERS . For verifying passwords, Django will find the hasher in the list that matches the algorithm name in the stored password.

How to set authentication in Django? ›

User authentication in Django¶
  1. Users.
  2. Permissions: Binary (yes/no) flags designating whether a user may perform a certain task.
  3. Groups: A generic way of applying labels and permissions to more than one user.
  4. A configurable password hashing system.
  5. Forms and view tools for logging in users, or restricting content.

How do we authenticate a custom user in Django? ›

Django provides an abstract base class AbstractUser to use as a starting point for creating your custom User model. AbstractUser Contains the most commonly used fields and methods for user authentication, such as username, email, password management, and permissions.

What is the difference between authentication and authorization? ›

Authentication and authorization are two vital information security processes that administrators use to protect systems and information. Authentication verifies the identity of a user or service, and authorization determines their access rights.

How to create custom validation in Django? ›

Firstly, we will need a Django model to perform validation. Next, we need a validator function that will take the field value and return it if it satisfies the custom validation; otherwise, it returns an error message. Finally, we need to integrate the validator function with the appropriate field in the Django model.

How to create custom permission in Django? ›

To implement a custom permission, override BasePermission and implement either, or both, of the following methods:
  1. .has_permission(self, request, view)
  2. .has_object_permission(self, request, view, obj)

How to create OTP in Django? ›

Creating an OTP Model

regex=r"^\d{10}", message="Phone number must be 10 digits only.")]) Once you've created the model in your app's 'models.py' file, you must update your database schema to include the new model. Here's how you do that: Make migrations: This step prepares the database for changes.

How to implement 2fa in Django? ›

Django Two-Factor Authentication Documentation
  1. Requirements. Django. Python. django-otp. ...
  2. Installation. Setup. Yubikey Setup.
  3. Configuration. General Settings. Twilio Gateway. Fake Gateway.
  4. Implementing. Limiting access to certain views. Enforcing two-factor. ...
  5. Management Commands. Status. Disable.
  6. Class Reference. Admin Site. Decorators.

References

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Geoffrey Lueilwitz

Last Updated:

Views: 6490

Rating: 5 / 5 (80 voted)

Reviews: 95% of readers found this page helpful

Author information

Name: Geoffrey Lueilwitz

Birthday: 1997-03-23

Address: 74183 Thomas Course, Port Micheal, OK 55446-1529

Phone: +13408645881558

Job: Global Representative

Hobby: Sailing, Vehicle restoration, Rowing, Ghost hunting, Scrapbooking, Rugby, Board sports

Introduction: My name is Geoffrey Lueilwitz, I am a zealous, encouraging, sparkling, enchanting, graceful, faithful, nice person who loves writing and wants to share my knowledge and understanding with you.