Authentication and Authorization Policy

The Django-AdminLTE2-PDQ package comes with built-in functionality to make it easy to customize and manage various user Authentication and Authorization policies and scenarios.

Note

This functionality is heavily based on the standard Django practices to manage view access and user permissions. We recommend reviewing that information before reading this section.

Important

Django-AdminLTE2-PDQ provides a middleware that is required for some of the available authentication and authorization functionality this package provides.

If you haven’t already done so, reference the Quickstart to add this middleware to your middleware list in settings.py so that you can use the full potential of this package.

Authentication

Authentication is the handling of user login, and view access when logged in or anonymous.

Setting up authentication for the package requires choosing if your site will:

• Require users to be logged in to gain access to the majority of site views.

• Allow anonymous users to see site views by default (this is the default Django handling).

If you would like to require that users are logged in to visit the majority of your site, see the Login Required section for more information on how to enable that.

Login Required

If you would like to prevent anonymous users from accessing the majority of the views in your site, you can require login by setting the ADMINLTE2_USE_LOGIN_REQUIRED setting in your settings.py file to True.

settings.py

ADMINLTE2_USE_LOGIN_REQUIRED = True

When enabled, the included middleware will redirect all requests made by an anonymous user to the login page unless the URL that they are trying to access is explicitly listed in a whitelist. The default whitelist contains the following standard anonymous routes:

• login - As defined via the LOGIN_URL setting in settings.py

• logout

• password_reset

• password_reset_done

• password_reset_confirm

• password_reset_complete

• media url - As defined via the MEDIA_URL setting in settings.py so long as it is not the default value of ''. See note below.

If you would like to add additional routes to this list, you can do so by adding either the route name or URL for the endpoint to the ADMINLTE2_LOGIN_EXEMPT_WHITELIST setting in your settings.py file.

settings.py

ADMINLTE2_LOGIN_EXEMPT_WHITELIST = [
    'two_factor_confirm',  # url_name of route to two factor confirmation
]

Tip

If the majority of your routes do not require being logged in and you only have a handful of routes that do, it is better to leave the ADMINLTE2_USE_LOGIN_REQUIRED undefined or set to False and instead use the Login Required Decorator or Login Required Mixin on the specific views that do require being logged in.

Note

The MEDIA_URL is exempt from the login required processing so long as it has a value other than the default.

By default, the MEDIA_URL setting is set to '', the blank string. This automatically gets converted to the root URL '/' to ensure that it is a valid URL and that there will be no issues when running your app.

If you leave the MEDIA_URL setting as the default and then try to serve media files from that location with the login required turned on, those files will not be able to be served to anonymous users.

Authorization

Authorization is the handling of user view access, based on the permissions and groups of a given logged in user.

Setting up authorization for the package requires Choosing a Policy and then properly using Decorators or Mixins provided by this package to set permissions on various views.

Setting the permissions on the view with the Decorators and Mixins provided by this package will prevent a user from accessing a view that they do not have permission to. Just like the ones provided by Django. But they will additionally dynamically show/hide any menu sidebar links for the protected view, in the, provided AdminLTE menus.

Note

Within this documentation and in the context of Choosing a Policy the Login Required Decorator and Login Required Mixin are included. Although these are not typically considered part of authorization they have been included in these sections because they will also handle showing and hiding a sidebar link depending on whether or not the user meets the criteria of being logged in.

Choosing a Policy

The first step in using and configuring authorization for views and sidebar menu links are to determine what general policy you want to adhere to. Regardless of whether you have the global Login Required turned on or off, knowing what type of policy you want to achieve is critical.

Your choices are:

1. Loose Policy - Has the following characteristics:

   • Majority of sidebar links and associated views are visible to all users.

   • Sidebar links and associated views will still be visible and accessible if you set required permissions or the login required criteria on that route’s view and that user meets the required criteria to access that view.

   • Sidebar links and associated views will be hidden / blocked if you set a required permission or the login required criteria on that route’s view and the user does not meet the required criteria to access that view.

   Warning

   If you have the global Login Required setting turned off and you opt for the Loose Policy you will be allowing all users, both logged in and anonymous, access to every view on your site that does not have a required permission or the login required criteria defined on the view.

2. Strict Policy - Has the following characteristics:

   • Majority of sidebar links and associated views are hidden to all users.

   • Sidebar links and associated views will become visible and accessible if you set required permissions or the login required criteria on a route’s view and the user meets the required criteria.

   • Sidebar links and associated views will become visible and accessible if you put the route in an explicit whitelist defined in the settings.

   Note

   With the Strict Policy, if you forget to add permissions to a view, the view will be inaccessible to everyone except for superusers. This is a good way to ensure that you don’t accidentally create features that everyone automatically has access to. You have to explicitly think about what permissions are required for each feature, set them on the view, and then assign the permissions to the users that need them before anyone can gain access to it.

Once you have determined what general policy you want to follow, use the corresponding section to properly set up and configure authorization.

Loose Policy

This policy assumes users should be able to see and access all links and views, by default.

When enabled, all views that do not use one of the included Decorators or Mixins will be accessible to everyone. Additionally, if the sidebar menu contains an entry for the view, the link to that view will be visible to everyone.

Views will only be hidden if one of the Decorators or Mixins are used and the user does not meet the required criteria. This will both prevent the user from being able to go directly to the view as well as hide any sidebar link that links to that view.

Refer to the Authentication & Authorization Configuration section for information about the specific settings in settings.py mentioned below.

1. Ensure that the ADMINLTE2_USE_STRICT_POLICY is either not defined in settings.py, or is set to False if it is defined.

   settings.py

   ADMINLTE2_USE_STRICT_POLICY = False
   

2. If you are using function based views, read the Authorizing Function Based Views page and follow the steps in the Loose Decorator Example section to add view permissions that require permission to access.

3. If you are using class based views, read the Authorizing Class Based Views page and follow the steps in the Loose Mixin Example section to add view permissions that require permission to access.

Strict Policy

This policy assumes users should have restricted access to links and views, by default.

When enabled, all views that do not use one of the included Decorators or Mixins will redirect all requests to the ADMINLTE2_HOME_ROUTE unless the route or url that they are trying to access is explicitly listed in a whitelist. The default whitelist contains the following standard anonymous routes as well as the password change, ADMINLTE2_HOME_ROUTE, media routes, and websocket routes:

• login - As defined via the LOGIN_URL setting in settings.py

• logout

• password_reset

• password_reset_done

• password_reset_confirm

• password_reset_complete

• password_change

• password_change_done

• home - As defined via the ADMINLTE2_HOME_ROUTE setting in settings.py

• media url - As defined via the MEDIA_URL setting in settings.py so long as it is not the default value of ''. See note below.

• websocket url - As defined via the WEBSOCKET_URL setting in settings.py. Defaults to /ws/.

Important

The Home route is included in the whitelist because we believe that there should be at least one view that a logged in user can access after logging in. Even if they do not have any required permissions to see anything else on the site. The alternative would be to send them to the login page after a successful login, which we believe, even with messages, would be confusing to the user.

Note

The MEDIA_URL is exempt from the login required processing so long as it has a value other than the default.

By default, the MEDIA_URL setting is set to '', the blank string. This automatically gets converted to the root URL '/' to ensure that it is a valid URL and that there will be no issues when running your app.

If you leave the MEDIA_URL setting as the default and then try to serve media files from that location with the login required turned on, those files will not be able to be served to anonymous users.

Additionally, if a view does have required permissions or login required criteria defined on the view, and the user does not meet that criteria, they will be redirected to the ADMINLTE2_HOME_ROUTE route.

Refer to the Authentication & Authorization Configuration section for information about the specific settings in settings.py mentioned below.

1. Ensure that the ADMINLTE2_USE_STRICT_POLICY is defined in settings.py and is set to True.

   settings.py

   ADMINLTE2_USE_STRICT_POLICY = True
   

2. If you are using function based views, read the Authorizing Function Based Views page and follow the steps in the Strict Decorator Example section to add view permissions that require permission to access.

3. If you are using class based views, read the Authorizing Class Based Views page and follow the steps in the Strict Mixin Example section to add view permissions that require permission to access.

4. Add any routes that do not require specific permissions and should be available to everyone to the ADMINLTE2_STRICT_POLICY_WHITELIST in settings.py

   settings.py

   ADMINLTE2_STRICT_POLICY_WHITELIST = [
       'tutorial'  # url_name of the route to the tutorial view.
   ]
   

Handling 404s and 403s

This section explains how the package handles 404 and 403 errors by default. Additionally, it shows what options are available if you would like to do something different than the default package behavior.

Handling 404 Errors

404s have a built-in handling behavior. This can be disabled if you do not want to use it, which will then just use the default Django handling.

Handling 404s with the Built-In Behavior

This package comes with built-in behavior to handle 404s, which is on by default The built-in functionality is to add a warning message via the Django messages framework indicating that the page does not exist. It will additionally add a debug message and log entry with specifics about what caused the 404 exception. It then redirects to the ADMINLTE2_HOME_ROUTE where the user can see those messages.

Note

The actual exception specifics are only rendered in a Debug message. This means that developers who have their message level set to include debug messages can see it, but in production where debug messages should not be shown, it will be not rendered.

The package does have some exceptions to the above handling of 404s. If the requested url is part of the static files, the media files, a favicon, or part of a special list in the settings, it will do the default Django 404 action by just raising a Http404 error and allowing Django to handle it.

The special setting that allows you to just raise a Http404 error is called ADMINLTE2_STRICT_POLICY_SERVE_404_FUZZY_WHITELIST. This setting can be added to settings.py and must contain a list of “starts with” patterns that should always be treated as actual 404s vs redirects to the home page. This is good for requests that might come directly from a browser via extensions or developer tools and are out of the developers control. Using this setting will prevent the server from sending back the entire home page for what should actually be a basic 404 response.

settings.py

ADMINLTE2_STRICT_POLICY_SERVE_404_FUZZY_WHITELIST = [
    "/.well-known/appspecific/com.chrome.devtools.json",
]

Handling 404s Manually

If you do not want to use the built-in handling for 404 errors and would like full control over how to handle them, you should disable the built-in behavior with the following setting:

settings.py

ADMINLTE2_REDIRECT_TO_HOME_ON_404 = False

Handling 403 Errors

403s also have a built-in handling behavior. This can also be disabled if you do not want to use it, which will then just use the default Django handling.

Handling 403s with the Built-In Behavior

To better understand how the built-in 403 handling works, we need to clarify some things. Permission Denied (403) can be raised primarily in one of two ways.

1. You are using the Strict Policy and you have not defined any permissions on a view that a user is trying to access.

2. Regardless of the Strict Policy, you have defined some required permissions on a view and the user does not meet the required criteria.

When this happens, we believe that it is good to do something different than the default behavior that Django provides of just returning a 403 error. We believe that it may be better to handle it as if it were a 404 so that users are unaware that the location they are trying to access has an actual endpoint that they do not have permission to access. It will make it harder for bad actors to phish for endpoints that they should not know exist.

Just like the built-in functionality for 404s, this package comes with built-in behavior to handle 403s, which is also on by default. The built-in functionality is to also add a warning message via the Django messages framework indicating that the page does not exist. It will additionally add a debug message and log entry with specifics about what caused the 403 exception. It then redirects to the ADMINLTE2_HOME_ROUTE where the user can see those messages.

Handling 403s Manually

If you do not want to use the built-in handling for 404 errors and would like full control over how to handle them, you should disable the built-in behavior with the following setting:

settings.py

ADMINLTE2_REDIRECT_TO_HOME_ON_404 = False

Customizing the built-in 404 and 403 messages

If you would like to customize the messages that are shown to the user when using the built-in 404 or 403 handling, you can set the following settings in settings.py. This will also allow you to use different messages for 403 errors in the event that you do not want it to operate the same as 404 errors.

settings.py

ADMINLTE2_RESPONSE_404_DEBUG_MESSAGE = "Nothing to see here!"

ADMINLTE2_RESPONSE_404_PRODUCTION_MESSAGE = "Nothing to see here!"

ADMINLTE2_RESPONSE_403_DEBUG_MESSAGE = "You lack the power!"

ADMINLTE2_RESPONSE_403_PRODUCTION_MESSAGE = "You lack the power!"