Login & Logout Flow

## Two steps, two jobs `django.contrib.auth` splits signing in into **verification** and **persistence**: | Function | Input | Output | Side effects | |---|---|---|---| | `authenticate(request, **credentials)` | credentials such as `username` and `password` | a user object or `None` | none on success; sends `user_login_failed` on failure | | `login(request, user, backend=None)` | a user object already verified | nothing | writes the session, sets `request.user`, rotates the CSRF token, sends `user_logged_in` | Keeping them apart lets you verify a password without logging anyone in (for example to confirm a sensitive action) and lets flows such as password reset log a user in without asking for credentials again. ## What authenticate() does 1. It iterates over `AUTHENTICATION_BACKENDS` in order, skipping any backend whose `authenticate()` signature cannot accept the keyword arguments you passed. 2. Each backend returns a user or `None`. The first user wins; Django sets `user.backend` to that backend's dotted path. 3. A backend may raise `PermissionDenied` to veto the login outright; `authenticate()` catches it, stops trying other backends and falls through to failure. 4. On failure it sends `user_login_failed` with the credentials cleansed of anything that looks like a password or token, and returns `None`. With the default `ModelBackend`, an account whose `is_active` is `False` is rejected here too, so `authenticate()` returns `None` for a deactivated member. ## What login() does `login()` assumes the user is genuine. It: - rotates the session key for an anonymous session with `cycle_key()`, or empties it with `flush()` if it belonged to a different user; - stores three keys: `_auth_user_id` (the primary key as a string), `_auth_user_backend` (the backend path) and `_auth_user_hash` (an HMAC of the password field); - sets `request.user` for the rest of the current request; - rotates the CSRF token and sends `user_logged_in`. The backend path matters. `login()` takes it from the `backend` argument or from `user.backend`, which `authenticate()` set. If neither exists and more than one backend is configured, it raises `ValueError` asking you to pass `backend`. With a single backend it uses that one. On every later request, `AuthenticationMiddleware` makes `request.user` a lazy object that reads those keys, asks the stored backend's `get_user()` for the user and checks the hash; if anything is missing or wrong you get an `AnonymousUser`. ## Putting them together A members-only gym portal's sign-in view verifies first and persists second: ```python user = authenticate(request, username=number, password=password) if user is not None: login(request, user) ``` Most projects never write this by hand: `LoginView` uses `AuthenticationForm`, whose `clean()` calls `authenticate()` and then `confirm_login_allowed()` (which rejects inactive users with an error message), and whose `form_valid()` calls `login()` with `form.get_user()`. ## What the next request sees The split also explains what happens after the response is sent. On the following request `AuthenticationMiddleware` installs a lazy `request.user`; the first access runs `get_user()`, which: - reads `_auth_user_id` and `_auth_user_backend` from the session; - checks that the backend path is still listed in `AUTHENTICATION_BACKENDS`; - calls that backend's `get_user(user_id)`, which for `ModelBackend` also rejects inactive accounts; - compares the stored `_auth_user_hash` with a freshly computed one. Any failure yields `AnonymousUser`, whose `is_authenticated` is `False`, whose `pk` is `None` and whose permission checks come back empty. That is why templates can test `user.is_authenticated` without first checking for `None`. ## Timing and enumeration `ModelBackend.authenticate()` runs the password hasher even when no account matches the username, by hashing the submitted password on a throwaway user instance. The response time is then similar for an unknown membership number and a wrong password, which makes it harder to discover which numbers exist. Custom backends should keep that property. ## Common mistakes - **Calling only `authenticate()`** and expecting the member to be logged in on the next page. Nothing was stored, so the next request sees `AnonymousUser`. - **Calling `login()` on a user fetched by primary key** without verifying anything, which is an authentication bypass if the key came from the request. - **Treating `None` as an exception path.** `authenticate()` does not raise for bad credentials; you must test for `None`. - **Assuming `login()` checks `is_active`.** It does not; the check lives in `ModelBackend` and in `AuthenticationForm`.