Authentication

Key features

• AUTH_USER_MODEL (default "auth.User") is the single source of truth for which model is "the" user model — every internal Django reference goes through it, never a hardcoded import
• get_user_model() returns the actual active user model at runtime — this is the correct way to reference it in code, not `from django.contrib.auth.models import User`
• A ForeignKey to the user model should be written as settings.AUTH_USER_MODEL (a string, avoiding a circular import) — not a direct import of User, which breaks the moment AUTH_USER_MODEL is swapped
• AbstractUser extends the default fields/behavior (username, email, is_staff, etc.) — appropriate when the default shape is close to what's needed, just extended
• AbstractBaseUser provides only password hashing and the authentication API surface, no fields at all — appropriate for a from-scratch shape (e.g. email-only login, no username field)
• Swapping AUTH_USER_MODEL after the first migrate has already run against the default User is NOT a supported, low-risk operation — Django's own docs recommend deciding this before any migrations exist

Command

# settings.py
AUTH_USER_MODEL = "accounts.User"

# accounts/models.py
class User(AbstractUser):
    ...

Key features

• authenticate(request, **credentials) checks credentials against AUTHENTICATION_BACKENDS and returns a User instance or None — it never touches the session
• login(request, user) is the separate call that actually establishes the session — always call it only after authenticate() (or equivalent verification) succeeds, never on an unverified user object
• AUTHENTICATION_BACKENDS defaults to ["django.contrib.auth.backends.ModelBackend"] — a list, tried in order, so multiple authentication mechanisms (SSO, API keys, legacy hashes) can coexist
• logout(request) clears the entire session, not just the auth-related keys — any other session data is lost too, unless explicitly preserved beforehand
• ModelBackend authenticates against USERNAME_FIELD (username by default, email if a custom user model sets USERNAME_FIELD = "email") — "username or email login" in practice means either a custom backend or setting USERNAME_FIELD, not a special authenticate() flag
• request.user is only populated because AuthenticationMiddleware runs on every request, reading the session established at login — removing that middleware means request.user is never set

Command

user = authenticate(request, username=..., password=...)
if user is not None:
    login(request, user)
...
logout(request)

Key features

• set_password(raw) hashes and stores; check_password(raw) verifies against the stored hash — a User is never saved with a plaintext password in either direction
• PASSWORD_HASHERS is an ordered list — the first entry hashes NEW passwords, but Django can still verify against a hash produced by any hasher later in the list, supporting a gradual algorithm migration
• AUTH_PASSWORD_VALIDATORS run at password set/change time (forms, not the User model itself) — a directly-created User via the ORM without going through a form/serializer bypasses them entirely
• PasswordResetTokenGenerator tokens are signed and encode a timestamp — they expire after PASSWORD_RESET_TIMEOUT (default 259200 seconds / 3 days) and are invalidated by certain user field changes (e.g. the password itself, or last_login in Django 5.x), making them naturally single-use
• is_superuser bypasses EVERY permission check, including custom ones evaluated via has_perm() — it does not just imply "all default permissions", it skips the check outright
• A Group is just a named bundle of Permission objects — user.has_perm() checks both permissions assigned directly to the user AND permissions inherited via any Group they belong to

Command

user.set_password(raw_password)
user.check_password(raw_password)
user.has_perm("app_label.codename")