<commit_before>====================================
Customizing authentication in Django
====================================

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. To customize
authentication to your projects needs involves understanding what points of the
provided system are extensible or replaceable. This document provides details
about how the auth system can be customized.

:ref:`Authentication backends <authentication-backends>` provide an extensible
system for when a username and password stored with the User model need
to be authenticated against a different service than Django's default.

You can give your models :ref:`custom permissions <custom-permissions>` that can be
checked through Django's authorization system.

You can :ref:`extend <extending-user>` the default User model, or :ref:`substitute
<auth-custom-user>` a completely customized model.

.. _authentication-backends:

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 authentication
methods.

For example, your company may already have an LDAP setup that stores a username
and password for every employee. It'd be a hassle for both the network
administrator and the users themselves if users had separate accounts in LDAP
and the Django-based applications.

So, to handle situations like this, the Django authentication system lets you
plug in other authentication sources. You can override Django's default
database-based scheme, or you can use the default system in tandem with other
systems.

See the :ref:`authentication backend reference
<authentication-backends-reference>` for information on the authentication
backends included with Django.

Specifying authentication backends
----------------------------------

Behind the scenes, Django maintains a list of "authentication backends" that it
checks for authentication. When somebody calls
:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
a user in <how-to-log-a-user-in>` -- Django tries authenticating across
all 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 the
:setting:`AUTHENTICATION_BACKENDS` setting. This should be a list of Python
path names that point to Python classes that know how to authenticate. These
classes can be anywhere on your Python path.

By default, :setting:`AUTHENTICATION_BACKENDS` is set to::

    ['django.contrib.auth.backends.ModelBackend']

That's the basic authentication backend that checks the Django users database
and queries the built-in permissions. It does not provide protection against
brute force attacks via any rate limiting mechanism. You may either implement
your own rate limiting mechanism in a custom auth backend, or use the
mechanisms provided by most Web servers.

The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
username and password is valid in multiple backends, Django will stop
processing at the first positive match.

If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception, authentication will immediately fail. Django won't check the
backends that follow.

.. note::

    Once a user has authenticated, Django stores which backend was used to
    authenticate the user in the user's session, and re-uses the same backend
    for the duration of that session whenever access to the currently
    authenticated user is needed. This effectively means that authentication
    sources are cached on a per-session basis, so if you change
    :setting:`AUTHENTICATION_BACKENDS`, you'll need to clear out session data if
    you need to force users to re-authenticate using different methods. A simple
    way to do that is simply 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 as
a set of optional permission related :ref:`authorization methods
<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.

The ``authenticate`` method takes a ``request`` argument and credentials as
keyword arguments. Most of the time, it'll just look like this::

    class MyBackend(object):
        def authenticate(self, request, username=None, password=<PASSWORD>):
            # Check the username/password and return a User.
            ...

But it could also authenticate a token, like so::

    class MyBackend(object):
        def authenticate(self, request, token=None):
            # Check the token and return a User.
            ...

Either way, ``authenticate`` should check the credentials it gets, and it
should return a ``User`` object that matches those credentials, if the
credentials are valid. If they're not valid, it should return ``None``.

``request`` is an :class:`~django.http.HttpRequest` and may be ``None`` if it
wasn't provided to :func:`~django.contrib.auth.authenticate` (which passes it
on to the backend).

The Django admin is tightly coupled to the Django :ref:`User object
<user-objects>`. 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 LDAP
directory, your external SQL database, etc.) You can either write a script to
do this in advance, or your ``authenticate`` method can do it the first time a
user logs in.

Here's an example backend that authenticates against a username and password
variable defined in your ``settings.py`` file and creates a Django ``User``
object the first time a user authenticates::

    from django.conf import settings
    from django.contrib.auth.hashers import check_password
    from django.contrib.auth.models import User

    class SettingsBackend(object):
        """
        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 = '<PASSWORD>='
        """

        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

.. versionchanged:: 1.11

    The ``request`` parameter was added to ``authenticate()`` and support for
    backends that don't accept it will be removed in Django 2.1.

.. _authorization_methods:

Handling authorization in custom backends
-----------------------------------------

Custom auth backends can provide their own permissions.

The user model will delegate permission lookup functions
(:meth:`~django.contrib.auth.models.User.get_group_permissions()`,
:meth:`~django.contrib.auth.models.User.get_all_permissions()`,
:meth:`~django.contrib.auth.models.User.has_perm()`, and
:meth:`~django.contrib.auth.models.User.has_module_perms()`) to any
authentication backend that implements these functions.

The permissions given to the user will be the superset of all permissions
returned by all backends. That is, Django grants a permission to a user that
any one backend grants.

If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception in :meth:`~django.contrib.auth.models.User.has_perm()` or
:meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization
will immediately fail and Django won't check the backends that follow.

The simple backend above could implement permissions for the magic admin
fairly simply::

    class SettingsBackend(object):
        ...
        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 associated
:class:`django.contrib.auth.models.User` functions, the backend auth functions
all take the user object, which may be an anonymous user, as an argument.

A full authorization implementation can be found in the ``ModelBackend`` class
in `django/contrib/auth/backends.py`_, which is the default backend and queries
the ``auth_permission`` table most of the time. If you wish to provide
custom behavior for only part of the backend API, you can take advantage of
Python inheritance and subclass ``ModelBackend`` instead of implementing the
complete API in a custom backend.

.. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py

.. _anonymous_auth:

Authorization for anonymous users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An anonymous user is one that is not authenticated i.e. they have provided no
valid authentication details. However, that does not necessarily mean they are
not authorized to do anything. At the most basic level, most websites
authorize anonymous users to browse most of the site, and many allow anonymous
posting of comments etc.

Django's permission framework does not have a place to store permissions for
anonymous users. However, the user object passed to an authentication backend
may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
the backend to specify custom authorization behavior for anonymous users. This
is especially useful for the authors of re-usable apps, who can delegate all
questions of authorization to the auth backend, rather than needing settings,
for example, to control anonymous access.

.. _inactive_auth:

Authorization for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An inactive user is a one that has its
:attr:`~django.contrib.auth.models.User.is_active` field set to ``False``. The
:class:`~django.contrib.auth.backends.ModelBackend` and
:class:`~django.contrib.auth.backends.RemoteUserBackend` authentication
backends prohibits these users from authenticating. If a custom user model
doesn't have an :attr:`~django.contrib.auth.models.CustomUser.is_active` field,
all users will be allowed to authenticate.

You can use :class:`~django.contrib.auth.backends.AllowAllUsersModelBackend`
or :class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend` if you
want to allow inactive users to authenticate.

The support for anonymous users in the permission system allows for a scenario
where anonymous users have permissions to do something while inactive
authenticated users do not.

Do not forget to test for the ``is_active`` attribute of the user in your own
backend permission methods.

.. versionchanged:: 1.10

    In older versions, the :class:`~django.contrib.auth.backends.ModelBackend`
    allowed inactive users to authenticate.

Handling object permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django's permission framework has a foundation for object permissions, though
there is no implementation for it in the core. That means that checking for
object permissions will always return ``False`` or an empty list (depending on
the check performed). An authentication backend will receive the keyword
parameters ``obj`` and ``user_obj`` for each object related authorization
method and can return the object level permission as appropriate.

.. _custom-permissions:

Custom permissions
==================

To create custom permissions for a given model object, use the ``permissions``
:ref:`model Meta attribute <meta-options>`.

This example Task model creates three custom permissions, i.e., actions users
can or cannot do with Task instances, specific to your application::

    class Task(models.Model):
        ...
        class Meta:
            permissions = (
                ("view_task", "Can see available tasks"),
                ("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 run
:djadmin:`manage.py migrate <migrate>` (the function that creates permissions
is connected to the :data:`~django.db.models.signals.post_migrate` signal).
Your code is in charge of checking the value of these permissions when a user
is trying to access the functionality provided by the application (viewing
tasks, changing the status of tasks, closing tasks.) Continuing the above
example, the following checks if a user may view tasks::

    user.has_perm('app.view_task')

.. _extending-user:

Extending the existing ``User`` model
=====================================

There are two ways to extend the default
:class:`~django.contrib.auth.models.User` model without substituting your own
model. If the changes you need are purely behavioral, and don't require any
change to what is stored in the database, you can create a :ref:`proxy model
<proxy-models>` based on :class:`~django.contrib.auth.models.User`. This
allows for any of the features offered by proxy models including default
ordering, custom managers, or custom model methods.

If you wish to store information related to ``User``, you can use a
:class:`~django.db.models.OneToOneField` to a model containing the fields for
additional 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 example
you might create an Employee model::

    from django.contrib.auth.models import User

    class Employee(models.Model):
        user = models.OneToOneField(User, on_delete=models.CASCADE)
        department = models.CharField(max_length=100)

Assuming an existing Employee <NAME> who has both a User and Employee
model, you can access the related information using Django's standard related
model 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 an
:class:`~django.contrib.admin.InlineModelAdmin` (for this example, we'll use a
:class:`~django.contrib.admin.StackedInline`) in your app's ``admin.py`` and
add it to a ``UserAdmin`` class which is registered with the
:class:`~django.contrib.auth.models.User` class::

    from django.contrib import admin
    from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
    from django.contrib.auth.models import User

    from my_user_profile_app.models import Employee

    # Define an inline admin descriptor for Employee model
    # which acts a bit like a singleton
    class EmployeeInline(admin.StackedInline):
        model = Employee
        can_delete = False
        verbose_name_plural = 'employee'

    # Define a new User admin
    class UserAdmin(BaseUserAdmin):
        inlines = (EmployeeInline, )

    # Re-register UserAdmin
    admin.site.unregister(User)
    admin.site.register(User, UserAdmin)

These profile models are not special in any way - they are just Django models that
happen to have a one-to-one link with a User model. As such, they do not get
auto created when a user is created, but
a :attr:`django.db.models.signals.post_save` could be used to create or update
related models as appropriate.

Note that using related models results in additional queries or joins to
retrieve the related data, and depending on your needs substituting the User
model and adding the related fields may be your better option.  However
existing links to the default User model within your project's apps may justify
the extra database load.

.. _auth-custom-user:

Substituting a custom ``User`` model
====================================

Some kinds of projects may have authentication requirements for which Django's
built-in :class:`~django.contrib.auth.models.User` model is not always
appropriate. For instance, on some sites it makes more sense to use an email
address as your identification token instead of a username.

Django allows you to override the default User model by providing a value for
the :setting:`AUTH_USER_MODEL` setting that references a custom model::

     AUTH_USER_MODEL = 'myapp.MyUser'

This dotted pair describes the name of the Django app (which must be in your
:setting:`INSTALLED_APPS`), and the name of the Django model that you wish to
use as your User model.

.. warning::

   Changing :setting:`AUTH_USER_MODEL` has a big effect on your database
   structure. It changes the tables that are available, and it will affect the
   construction of foreign keys and many-to-many relationships. If you intend
   to set :setting:`AUTH_USER_MODEL`, you should set it before creating
   any migrations or running ``manage.py migrate`` for the first time.

   Changing this setting after you have tables created is not supported
   by :djadmin:`makemigrations` and will result in you having to manually
   fix your schema, port your data from the old user table, and possibly
   manually reapply some migrations.

.. warning::

   Due to limitations of Django's dynamic dependency feature for swappable
   models, you must ensure that the model referenced by :setting:`AUTH_USER_MODEL`
   is created in the first migration of its app (usually called ``0001_initial``);
   otherwise, you will have dependency issues.

   In addition, you may run into a CircularDependencyError when running your
   migrations as Django won't be able to automatically break the dependency
   loop due to the dynamic dependency. If you see this error, you should
   break the loop by 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 other and seeing how ``makemigrations`` resolves that
   circular dependency if you want to see how it's usually done)

.. admonition:: Reusable apps and ``AUTH_USER_MODEL``

   Reusable apps shouldn't implement a custom user model. A project may use
   many apps, and two reusable apps that implemented a custom user model
   couldn't be used together. If you need to store per user information in your
   app, use a :class:`~django.db.models.ForeignKey` or
   :class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
   as described below.

Referencing the ``User`` model
------------------------------<commit_msg>Fixed #24370 -- Recommended starting with a custom user model.<commit_after>====================================
Customizing authentication in Django
====================================

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. To customize
authentication to your projects needs involves understanding what points of the
provided system are extensible or replaceable. This document provides details
about how the auth system can be customized.

:ref:`Authentication backends <authentication-backends>` provide an extensible
system for when a username and password stored with the User model need
to be authenticated against a different service than Django's default.

You can give your models :ref:`custom permissions <custom-permissions>` that can be
checked through Django's authorization system.

You can :ref:`extend <extending-user>` the default User model, or :ref:`substitute
<auth-custom-user>` a completely customized model.

.. _authentication-backends:

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 authentication
methods.

For example, your company may already have an LDAP setup that stores a username
and password for every employee. It'd be a hassle for both the network
administrator and the users themselves if users had separate accounts in LDAP
and the Django-based applications.

So, to handle situations like this, the Django authentication system lets you
plug in other authentication sources. You can override Django's default
database-based scheme, or you can use the default system in tandem with other
systems.

See the :ref:`authentication backend reference
<authentication-backends-reference>` for information on the authentication
backends included with Django.

Specifying authentication backends
----------------------------------

Behind the scenes, Django maintains a list of "authentication backends" that it
checks for authentication. When somebody calls
:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
a user in <how-to-log-a-user-in>` -- Django tries authenticating across
all 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 the
:setting:`AUTHENTICATION_BACKENDS` setting. This should be a list of Python
path names that point to Python classes that know how to authenticate. These
classes can be anywhere on your Python path.

By default, :setting:`AUTHENTICATION_BACKENDS` is set to::

    ['django.contrib.auth.backends.ModelBackend']

That's the basic authentication backend that checks the Django users database
and queries the built-in permissions. It does not provide protection against
brute force attacks via any rate limiting mechanism. You may either implement
your own rate limiting mechanism in a custom auth backend, or use the
mechanisms provided by most Web servers.

The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
username and password is valid in multiple backends, Django will stop
processing at the first positive match.

If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception, authentication will immediately fail. Django won't check the
backends that follow.

.. note::

    Once a user has authenticated, Django stores which backend was used to
    authenticate the user in the user's session, and re-uses the same backend
    for the duration of that session whenever access to the currently
    authenticated user is needed. This effectively means that authentication
    sources are cached on a per-session basis, so if you change
    :setting:`AUTHENTICATION_BACKENDS`, you'll need to clear out session data if
    you need to force users to re-authenticate using different methods. A simple
    way to do that is simply 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 as
a set of optional permission related :ref:`authorization methods
<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.

The ``authenticate`` method takes a ``request`` argument and credentials as
keyword arguments. Most of the time, it'll just look like this::

    class MyBackend(object):
        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::

    class MyBackend(object):
        def authenticate(self, request, token=None):
            # Check the token and return a User.
            ...

Either way, ``authenticate`` should check the credentials it gets, and it
should return a ``User`` object that matches those credentials, if the
credentials are valid. If they're not valid, it should return ``None``.

``request`` is an :class:`~django.http.HttpRequest` and may be ``None`` if it
wasn't provided to :func:`~django.contrib.auth.authenticate` (which passes it
on to the backend).

The Django admin is tightly coupled to the Django :ref:`User object
<user-objects>`. 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 LDAP
directory, your external SQL database, etc.) You can either write a script to
do this in advance, or your ``authenticate`` method can do it the first time a
user logs in.

Here's an example backend that authenticates against a username and password
variable defined in your ``settings.py`` file and creates a Django ``User``
object the first time a user authenticates::

    from django.conf import settings
    from django.contrib.auth.hashers import check_password
    from django.contrib.auth.models import User

    class SettingsBackend(object):
        """
        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 = '<PASSWORD>='
        """

        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

.. versionchanged:: 1.11

    The ``request`` parameter was added to ``authenticate()`` and support for
    backends that don't accept it will be removed in Django 2.1.

.. _authorization_methods:

Handling authorization in custom backends
-----------------------------------------

Custom auth backends can provide their own permissions.

The user model will delegate permission lookup functions
(:meth:`~django.contrib.auth.models.User.get_group_permissions()`,
:meth:`~django.contrib.auth.models.User.get_all_permissions()`,
:meth:`~django.contrib.auth.models.User.has_perm()`, and
:meth:`~django.contrib.auth.models.User.has_module_perms()`) to any
authentication backend that implements these functions.

The permissions given to the user will be the superset of all permissions
returned by all backends. That is, Django grants a permission to a user that
any one backend grants.

If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception in :meth:`~django.contrib.auth.models.User.has_perm()` or
:meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization
will immediately fail and Django won't check the backends that follow.

The simple backend above could implement permissions for the magic admin
fairly simply::

    class SettingsBackend(object):
        ...
        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 associated
:class:`django.contrib.auth.models.User` functions, the backend auth functions
all take the user object, which may be an anonymous user, as an argument.

A full authorization implementation can be found in the ``ModelBackend`` class
in `django/contrib/auth/backends.py`_, which is the default backend and queries
the ``auth_permission`` table most of the time. If you wish to provide
custom behavior for only part of the backend API, you can take advantage of
Python inheritance and subclass ``ModelBackend`` instead of implementing the
complete API in a custom backend.

.. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py

.. _anonymous_auth:

Authorization for anonymous users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An anonymous user is one that is not authenticated i.e. they have provided no
valid authentication details. However, that does not necessarily mean they are
not authorized to do anything. At the most basic level, most websites
authorize anonymous users to browse most of the site, and many allow anonymous
posting of comments etc.

Django's permission framework does not have a place to store permissions for
anonymous users. However, the user object passed to an authentication backend
may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
the backend to specify custom authorization behavior for anonymous users. This
is especially useful for the authors of re-usable apps, who can delegate all
questions of authorization to the auth backend, rather than needing settings,
for example, to control anonymous access.

.. _inactive_auth:

Authorization for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An inactive user is a one that has its
:attr:`~django.contrib.auth.models.User.is_active` field set to ``False``. The
:class:`~django.contrib.auth.backends.ModelBackend` and
:class:`~django.contrib.auth.backends.RemoteUserBackend` authentication
backends prohibits these users from authenticating. If a custom user model
doesn't have an :attr:`~django.contrib.auth.models.CustomUser.is_active` field,
all users will be allowed to authenticate.

You can use :class:`~django.contrib.auth.backends.AllowAllUsersModelBackend`
or :class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend` if you
want to allow inactive users to authenticate.

The support for anonymous users in the permission system allows for a scenario
where anonymous users have permissions to do something while inactive
authenticated users do not.

Do not forget to test for the ``is_active`` attribute of the user in your own
backend permission methods.

.. versionchanged:: 1.10

    In older versions, the :class:`~django.contrib.auth.backends.ModelBackend`
    allowed inactive users to authenticate.

Handling object permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django's permission framework has a foundation for object permissions, though
there is no implementation for it in the core. That means that checking for
object permissions will always return ``False`` or an empty list (depending on
the check performed). An authentication backend will receive the keyword
parameters ``obj`` and ``user_obj`` for each object related authorization
method and can return the object level permission as appropriate.

.. _custom-permissions:

Custom permissions
==================

To create custom permissions for a given model object, use the ``permissions``
:ref:`model Meta attribute <meta-options>`.

This example Task model creates three custom permissions, i.e., actions users
can or cannot do with Task instances, specific to your application::

    class Task(models.Model):
        ...
        class Meta:
            permissions = (
                ("view_task", "Can see available tasks"),
                ("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 run
:djadmin:`manage.py migrate <migrate>` (the function that creates permissions
is connected to the :data:`~django.db.models.signals.post_migrate` signal).
Your code is in charge of checking the value of these permissions when a user
is trying to access the functionality provided by the application (viewing
tasks, changing the status of tasks, closing tasks.) Continuing the above
example, the following checks if a user may view tasks::

    user.has_perm('app.view_task')

.. _extending-user:

Extending the existing ``User`` model
=====================================

There are two ways to extend the default
:class:`~django.contrib.auth.models.User` model without substituting your own
model. If the changes you need are purely behavioral, and don't require any
change to what is stored in the database, you can create a :ref:`proxy model
<proxy-models>` based on :class:`~django.contrib.auth.models.User`. This
allows for any of the features offered by proxy models including default
ordering, custom managers, or custom model methods.

If you wish to store information related to ``User``, you can use a
:class:`~django.db.models.OneToOneField` to a model containing the fields for
additional 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 example
you might create an Employee model::

    from django.contrib.auth.models import User

    class Employee(models.Model):
        user = models.OneToOneField(User, on_delete=models.CASCADE)
        department = models.CharField(max_length=100)

Assuming an existing Employee <NAME> who has both a User and Employee
model, you can access the related information using Django's standard related
model 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 an
:class:`~django.contrib.admin.InlineModelAdmin` (for this example, we'll use a
:class:`~django.contrib.admin.StackedInline`) in your app's ``admin.py`` and
add it to a ``UserAdmin`` class which is registered with the
:class:`~django.contrib.auth.models.User` class::

    from django.contrib import admin
    from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
    from django.contrib.auth.models import User

    from my_user_profile_app.models import Employee

    # Define an inline admin descriptor for Employee model
    # which acts a bit like a singleton
    class EmployeeInline(admin.StackedInline):
        model = Employee
        can_delete = False
        verbose_name_plural = 'employee'

    # Define a new User admin
    class UserAdmin(BaseUserAdmin):
        inlines = (EmployeeInline, )

    # Re-register UserAdmin
    admin.site.unregister(User)
    admin.site.register(User, UserAdmin)

These profile models are not special in any way - they are just Django models that
happen to have a one-to-one link with a User model. As such, they do not get
auto created when a user is created, but
a :attr:`django.db.models.signals.post_save` could be used to create or update
related models as appropriate.

Note that using related models results in additional queries or joins to
retrieve the related data, and depending on your needs substituting the User
model and adding the related fields may be your better option.  However
existing links to the default User model within your project's apps may justify
the extra database load.

.. _auth-custom-user:

Substituting a custom ``User`` model
====================================

Some kinds of projects may have authentication requirements for which Django's
built-in :class:`~django.contrib.auth.models.User` model is not always
appropriate. For instance, on some sites it makes more sense to use an email
address as your identification token instead of a username.

Django allows you to override the default User model by providing a value for
the :setting:`AUTH_USER_MODEL` setting that references a custom model::

     AUTH_USER_MODEL = 'myapp.MyUser'

This dotted pair describes the name of the Django app (which must be in your
:setting:`INSTALLED_APPS`), and the name of the 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 custom
user model, even if the default :class:`~django.contrib.auth.models.User` model
is sufficient for you. This model behaves identically to the default user
model, but you'll be able to customize it in the future if the need arises::

    from django.conf.auth.models import AbstractUser

    class User(AbstractUser):
        pass

Don't forget to point :setting:`AUTH_USER_MODEL` to it. Do this before creating
any migrations or running ``manage.py migrate`` for the first time.

Changing to a custom user model mid-project
-------------------------------------------

Changing :setting:`AUTH_USER_MODEL` after you've created database tables is
significantly more difficult since it affects foreign keys and many-to-many
relationships, for example.

This change can't be done automatically and requires manually fixing your
schema, moving your data from the old user table, and possibly manually
reapplying some migrations. See :ticket:`25313` for an outline of the steps.

Due to limitations of Django's dynamic dependency feature for swappable
models, the model referenced by :setting:`AUTH_USER_MODEL` must be created in
the 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 your
migrations as Django won't be able to automatically break the dependency loop
due to the dynamic dependency. If you see this error, you should break the loop
by 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 other
and seeing how ``makemigrations`` resolves that circular dependency if you want
to 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 many
apps, and two reusable apps that implemented a custom user model couldn't be
used together. If you need to store per user information in your app, use
a :class:`~django.db.models.ForeignKey` or
:class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
as described below.

Referencing the ``User`` model
------------------------------
{'fraction_non_alphanumeric': 0.0880603138783465, 'fraction_numerical': 0.0010257462303826033, 'mean_word_length': 3.9526289052578103, 'pattern_counts': {'":': 0, '<': 30, '<?xml version=': 0, '>': 42, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4129653', 'n_tokens_mistral': 9828, 'n_tokens_neox': 9373, 'n_words': 4746}