Skip to main content

Administrative Tools and CLI

This tutorial guides you through managing users, groups, and security settings using the command-line interface (CLI) and the Django admin site. You will learn how to create administrative accounts, update passwords, and configure the specialized admin classes provided by this codebase.

Prerequisites​

To follow this tutorial, ensure you have the following apps in your INSTALLED_APPS setting:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    # ...
]

Step 1: Initial Setup via CLI​

Before you can access the web-based admin interface, you need a superuser account. The createsuperuser command allows you to create an account with full permissions.

Interactive Mode​

Run the following command in your terminal and follow the prompts:

python manage.py createsuperuser

The command will prompt you for a username, email address, and password. It uses django.contrib.auth.password_validation to ensure your password meets security requirements.

Non-Interactive Mode (CI/CD)​

For automated deployments, you can use environment variables and the --noinput flag:

export DJANGO_SUPERUSER_PASSWORD="my-secure-password"
python manage.py createsuperuser \
    --username admin \
    --email admin@example.com \
    --noinput

The createsuperuser.Command class looks for environment variables prefixed with DJANGO_SUPERUSER_ for any required fields.

Step 2: Emergency Password Management​

If you lose access to an account, use the changepassword command. This tool bypasses the web interface and updates the database directly.

python manage.py changepassword <username>

The changepassword.Command will prompt you to enter and confirm the new password. It validates the new password against the user instance before saving it to the database.

Step 3: Configuring the Admin Interface​

To manage users and groups through the web UI, you must register the specialized UserAdmin and GroupAdmin classes in your admin.py file.

from django.contrib import admin
from django.contrib.auth.models import User, Group
from django.contrib.auth.admin import UserAdmin, GroupAdmin

# Unregister defaults if they were already registered
admin.site.unregister(User)
admin.site.unregister(Group)

# Register with specialized admin classes
admin.site.register(User, UserAdmin)
admin.site.register(Group, GroupAdmin)

UserAdmin Features​

The UserAdmin class provides a customized experience for user management:

  • Fieldsets: Organizes user data into sections like "Personal info", "Permissions", and "Important dates".
  • Password Handling: Uses AdminUserCreationForm for new users and AdminPasswordChangeForm for existing ones, ensuring passwords are never stored in plain text.
  • Security Check: The _add_view method enforces a strict security rule: a staff member must have both "Add user" and "Change user" permissions to create a new user. This prevents a user with limited permissions from creating a superuser.

GroupAdmin Optimization​

The GroupAdmin class is optimized for performance. It uses select_related("content_type") in the formfield_for_manytomany method to avoid N+1 database queries when loading the list of available permissions.

Step 4: Customizing User Management​

If you have a custom user model or need to add fields to the admin, subclass UserAdmin.

from django.contrib.auth.admin import UserAdmin
from .models import MyCustomUser

class MyUserAdmin(UserAdmin):
    # Add custom fields to the list display
    list_display = ("username", "email", "is_staff", "custom_profile_field")
    
    # Add custom fields to the edit form
    fieldsets = UserAdmin.fieldsets + (
        ("Extra Profile Info", {"fields": ("custom_profile_field",)}),
    )

admin.site.register(MyCustomUser, MyUserAdmin)

When customizing, remember that UserAdmin uses add_fieldsets specifically for the creation form. If your custom fields are required during user creation, you must add them there as well.

Summary​

By completing this tutorial, you have:

  1. Created a superuser using the createsuperuser CLI tool.
  2. Managed passwords via the changepassword command.
  3. Registered UserAdmin and GroupAdmin to provide a secure, optimized interface for managing permissions.
  4. Learned how to extend the administrative tools for custom requirements.

For next steps, explore django.contrib.auth.password_validation to customize the security rules enforced by these tools.