Authentication and Authorization

Overview

In your final project you already know how to build REST APIs and how authentication and authorization work in theory. In this chapter you will apply those ideas to a real, production-style backend.

You will design and implement a realistic authentication and authorization system that can safely run in production, integrate with PostgreSQL and Redis, and support your application’s needs as it grows.

The goal here is not to re-explain basic concepts like “what is a JWT” or “what is RBAC,” but to show how to wire everything together in a complete project, with production-ready decisions and trade-offs.

Requirements for Auth in a Production Project

Before choosing tools or writing code, define what your application actually needs.

Typical requirements for the final project backend:

• Users can:
• Register with email and password.
• Confirm their email address.
• Log in with email and password.
• Log out (invalidate tokens or sessions).
• Request a password reset and set a new password.
• The system must:
• Store passwords securely.
• Issue short-lived access tokens and longer-lived refresh tokens.
• Protect sensitive endpoints with authentication.
• Support at least basic role-based authorization (for example user, admin).
• Provide an admin-only API section.
• Work correctly in a distributed environment with multiple app instances.

List these needs explicitly in your project docs. It will guide your design and help you test the right things.

Designing Your Auth and AuthZ Architecture

Tokens vs Sessions

For this final project, a token-based architecture fits well with a REST API and modern frontends:

• Stateless access tokens.
• Stateful refresh tokens (stored server-side in Redis or database, or implemented with rotation).

A common design:

• Access token
• Format: JWT.
• Lifetime: short, for example 5 to 15 minutes.
• Content: user id, roles, and maybe a small set of claims (never secrets).
• Refresh token
• Format: opaque random string (or JWT) stored server-side.
• Lifetime: longer, for example 7 to 30 days.
• Storage: HTTP-only cookie or secure storage in the client.
• Use: only to obtain a new access token.

Where tokens live

Practical options for your project:

For a backend-only course project, you can:

• Assume the frontend will store the access token in memory.
• Deliver the refresh token as:
• HTTP-only cookie for browser clients, or
• In the response body for non-browser clients, which then store it safely.

Document this choice in your project README.

Data Model for Users, Roles and Permissions

User table

At minimum your users table needs:

Keep password_hash separate from any other user data. Never mix plain password with hash in code.

Roles and permissions

For a real production system you might have:

• roles table.
• permissions table.
• role_permissions join table.
• user_roles table.

For this project you can choose between:

1. Simple roles in the user table
• Columns: is_superuser, maybe role enum: user, staff, admin.
• Fast to implement, fine for small projects.
2. Full RBAC tables
• More flexible but more work and more queries.

For a beginner-friendly final project, a hybrid that uses:

• is_superuser flag for full admin access.
• A role enum for user, manager, admin if you want more nuance.

is enough to demonstrate authorization patterns without lots of extra complexity.

Password Storage and Authentication Flow

Password hashing

Use a strong, adaptive password hashing algorithm like bcrypt or argon2id.

Implementation rules:

With Python you can use:

• passlib with bcrypt.
• Or argon2-cffi for Argon2.

Pseudocode for hashing:

hashed = hash_password(plain_password)
user.password_hash = hashed

Pseudocode for verification:

if not verify_password(candidate_password, user.password_hash):
    raise InvalidCredentialsError()

Never log the plain password. You can log that a login failed, but not the credentials.

Login flow

The typical login endpoint:

1. Receive email and password.
2. Find user by email (case insensitive).
3. If user not found or is_active is false, respond with a generic error.
4. Verify password.
5. If password correct:
• Generate access and refresh tokens.
• Optionally, store refresh token info (user id, device, expires at) in DB or Redis.
• Update last_login_at.
6. Return tokens to the client.

Return the same error message for "user not found" and "wrong password" to avoid revealing which emails exist.

Example response body:

{
  "access_token": "<jwt-access>",
  "refresh_token": "<opaque-or-jwt-refresh>",
  "token_type": "bearer",
  "expires_in": 900
}

If you use HTTP-only cookies for refresh tokens, the refresh_token might not appear in the JSON.

Access and Refresh Tokens in Your Project

Designing JWT payloads

Your JWT payload should include only what you need to check authorization quickly.

A minimal example:

{
  "sub": "user_id_here",
  "exp": 1700000000,
  "iat": 1699996400,
  "type": "access",
  "is_superuser": false,
  "role": "user"
}

Key fields:

• sub: subject, usually user id.
• exp: expiration timestamp.
• iat: issued at timestamp.
• type: "access" or "refresh" if you use JWT refresh tokens.
• A few auth-related claims: role or flags.

Signing and verifying tokens

Use a strong secret key for HMAC signing (HS256) and store it in an environment variable, not in code.

For example:

• JWT_SECRET_KEY
• JWT_REFRESH_SECRET_KEY (if you want separate keys)

Use environment variables and your configuration system, not hardcoded literals.

Token creation pseudocode:

def create_access_token(user_id: str, is_superuser: bool, role: str) -> str:
    now = datetime.utcnow()
    payload = {
        "sub": user_id,
        "type": "access",
        "is_superuser": is_superuser,
        "role": role,
        "iat": int(now.timestamp()),
        "exp": int((now + ACCESS_TOKEN_LIFETIME).timestamp())
    }
    return encode_jwt(payload, secret=JWT_SECRET_KEY, algorithm="HS256")

Always check:

• Signature.
• exp is in the future.
• type is "access" when using it as access token.

Refresh tokens and rotation

Refresh tokens are more sensitive, because they live longer.

To make them safer:

• Give them a unique ID (jti claim or random string).
• Store them server-side with:
• User id.
• Expiration.
• A status flag (valid, revoked).
• On token refresh:
• Validate refresh token.
• Create a new access token.
• Optionally:
• Invalidate the old refresh token.
• Issue a new refresh token (rotation).

If a refresh token leaks, you want to be able to revoke it quickly.

You can store refresh tokens in:

• PostgreSQL table user_refresh_tokens.
• Or Redis, keyed by a token ID or random string.

Example Redis key pattern:

• refresh_token:<token_id> -> {user_id, expires_at}

---

Integrating Auth with PostgreSQL and Redis

Storing data in PostgreSQL

Use PostgreSQL for:

• Users and their profile data.
• Roles and admin flags.
• Email verification records.
• Password reset tokens.
• Persistent refresh tokens if you want a complete history.

Example PostgreSQL tables:

• users
• email_verification_tokens
• password_reset_tokens
• user_refresh_tokens (optional if not using Redis)

Design email_verification_tokens like:

You can also make token a signed value that contains only the user id and expiry, verified using your secret key. In that case you do not need a separate table.

Storing ephemeral data in Redis

Use Redis for short-lived or frequent operations:

• Rate limiting authentication attempts.
• Blacklist or invalidate specific tokens quickly.
• Storing current active sessions.
• Short TTL email verification or password reset tokens.

Examples:

• Failed login attempts per IP or email:
• Key: auth:login_attempts:<ip-or-email>
• Value: integer count
• TTL: 15 minutes
• Blacklisted JWT IDs:
• Key: jwt:blacklist:<jti>
• Value: "1"
• TTL: until original exp

Your FastAPI dependency that validates tokens can check Redis for jwt:blacklist:<jti>. If it exists, treat the token as invalid.

Implementing Authentication in the Final Project

Endpoints to implement

At minimum, your final project should include these auth endpoints:

1. POST /auth/register
• Input: email, password, maybe full_name.
• Behavior:
• Create user.
• Hash password.
• Set email_verified to false.
• Send verification email (in background).
• Response: success message or created user data (never password hash).
2. POST /auth/login
• Input: email, password.
• Behavior:
• Check credentials.
• Create access and refresh tokens.
• Maybe set refresh token as HTTP-only cookie.
• Response: token pair.
3. POST /auth/refresh
• Input: refresh token (body or cookie).
• Behavior:
• Validate refresh token and its status.
• Optionally rotate refresh token.
• Issue new access token.
• Response: new tokens.
4. POST /auth/logout
• Input: refresh token.
• Behavior:
• Invalidate refresh token in DB or Redis.
• Response: success message.
5. POST /auth/verify-email
• Input: verification token (usually passed in URL query).
• Behavior:
• Validate token.
• Mark user email as verified.
• Response: success message.
6. POST /auth/request-password-reset
• Input: email.
• Behavior:
• If user exists, send reset email with one-time token.
• Response: generic success message (same for existing or non-existing email).
7. POST /auth/reset-password
• Input: token, new_password.
• Behavior:
• Validate token.
• Update password hash.
• Response: success message.

These endpoints should be covered by tests in your final project.

FastAPI dependencies for auth

Centralize token decoding and user loading into reusable dependencies.

Common pattern:

• get_current_user:
• Reads Authorization: Bearer <token> header.
• Validates JWT.
• Loads user from database.
• Checks is_active.
• get_current_active_user:
• Wraps get_current_user.
• Additionally checks user.is_active and user.email_verified.

Pseudocode:

async def get_current_user(token: str = Depends(oauth2_scheme),
                           session: AsyncSession = Depends(get_db)):
    payload = decode_jwt(token)
    user_id = payload["sub"]
    user = await get_user_by_id(session, user_id)
    if not user or not user.is_active:
        raise HTTPException(status_code=401, detail="Inactive or invalid user")
    return user

Use these dependencies in your routers to keep the code DRY.

Authorization Rules in a Real Project

Protecting endpoints

For each API endpoint in the final project, you need to decide:

• Public, no auth required.
• Authenticated user required.
• Admin or elevated role required.
• Resource owner only (for example, only owner can update a task).

Examples:

• Public:
• POST /auth/register
• POST /auth/login
• POST /auth/request-password-reset
• Authenticated:
• GET /me
• GET /orders/my
• POST /tasks
• Admin:
• GET /admin/users
• DELETE /admin/users/{id}

Implementing role checks

Use separate dependencies for role-based checks, for example:

• get_current_admin:
• Uses get_current_user.
• Checks user.is_superuser or user.role == "admin".

Pseudocode:

async def get_current_admin(user: User = Depends(get_current_user)):
    if not user.is_superuser:
        raise HTTPException(status_code=403, detail="Not enough permissions")
    return user

Then annotate admin-only endpoints:

@router.get("/admin/users")
async def list_users(admin: User = Depends(get_current_admin)):
    ...

This keeps authorization logic at the edges of your API, not inside business logic.

Resource ownership

For operations on resources like tasks, orders, or files, you often need to ensure the user is the owner.

Pattern:

1. Load resource from database by its id.
2. Check if resource.owner_id == current_user.id.
3. If not, return 403 Forbidden.

Example:

async def get_task_or_404(task_id: int, session: AsyncSession):
    task = await session.get(Task, task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="Task not found")
    return task
@router.put("/tasks/{task_id}")
async def update_task(
    task_id: int,
    data: TaskUpdate,
    user: User = Depends(get_current_user),
    session: AsyncSession = Depends(get_db)
):
    task = await get_task_or_404(task_id, session)
    if task.owner_id != user.id and not user.is_superuser:
        raise HTTPException(status_code=403, detail="Not enough permissions")
    ...

Avoid exposing details about whether the resource exists for unauthorized users. You may choose between returning 404 or 403 based on your threat model, but be consistent.

Protecting Auth in a Production Environment

Rate limiting login and reset endpoints

Authentication endpoints are frequent targets for abuse, such as brute force attacks.

Use Redis-based rate limiting:

• Limit by IP.
• Optionally also limit by email or username.

Example rule:

Implementation idea:

1. When a login fails:
• Increment auth:login:fail:<ip> in Redis.
• Set TTL to 15 minutes if key was new.
2. Before processing a login:
• Check that counter is below your threshold.
• If above, return 429 Too Many Requests.

You can use similar rules for:

• Password reset requests.
• Email verification link requests.

Protect tokens in transit

Configure your production environment as follows:

• Only use HTTPS for all requests.
• Set Secure flag on cookies that carry refresh tokens.
• Use SameSite attributes correctly, typically Lax or Strict for your use case.

When behind a reverse proxy like Nginx or Traefik:

• Ensure correct handling of X-Forwarded-Proto.
• Configure your app to treat incoming traffic as HTTPS when it is.

Token invalidation and logout

In a purely stateless JWT setup, logout is not straightforward. For a production system you should support some level of invalidation.

Options:

1. Short-lived access tokens, long-lived refresh tokens
• Access tokens expire soon.
• Logout simply deletes or revokes the refresh token on the server.
2. Blacklist (denylist) JWT IDs in Redis
• Each JWT has a unique jti claim.
• On logout, add jti to Redis with TTL equal to token’s remaining life.
• Check against Redis in the auth dependency.

Even if you choose a simpler approach for your project, document your token invalidation strategy clearly.

Email Verification and Password Reset

Email verification flow

In the final project, your verification flow could be:

1. POST /auth/register creates user with email_verified = false.
2. It creates a verification token:
• Random string or signed JWT with user_id and expiry.
• TTL, for example 24 hours.
3. Send email with verification link:
• URL: https://frontend-app/verify-email?token=<token>.
4. Frontend calls POST /auth/verify-email with that token.
5. Backend:
• Verifies token.
• Ensures not used or expired.
• Sets email_verified = true.

Do not leak whether a token is valid or not in a way that helps an attacker enumerate users. Generic error messages are usually safer.

Password reset flow

Very similar idea:

1. POST /auth/request-password-reset:
• If user exists:
• Generate one-time reset token.
• Store it with TTL, for example 1 hour.
• Send email with reset link.
• Always return 200 OK with generic message.
2. POST /auth/reset-password:
• Input: token, new_password.
• Validate token.
• Update password hash.
• Invalidate that token so it cannot be reused.

Tokens for reset should be:

• Random with enough entropy (for example 32 bytes base64).
• Single-use.
• Time-limited.

---

Testing Authentication and Authorization

For the final project you should have automated tests that cover the critical paths.

What to test

Suggested test list:

• Registration:
• Successful registration.
• Duplicate email fails.
• Password minimum length enforced.
• Login:
• Successful login returns a valid access token.
• Invalid password fails.
• Inactive user cannot log in.
• Access token:
• Protected endpoint returns 401 without token.
• Protected endpoint returns 200 with valid token.
• Expired token returns 401.
• Token with invalid signature returns 401.
• Refresh:
• Using valid refresh token returns new access token.
• Revoked refresh token fails.
• Email verification:
• Unverified user cannot access endpoints that require verified email (if you enforce this).
• Verifying email flips email_verified flag.
• Password reset:
• Requesting password reset produces a token.
• Using token updates password.
• Token cannot be reused.
• Authorization:
• Normal user cannot access admin endpoints.
• Admin user can access admin endpoints.
• User cannot update resources of other users.

Using fixtures and helpers

Create helper functions for tests:

• create_user(...).
• login_user(...) that returns access token.
• auth_client(user) that returns a test client with Authorization header already set.

This makes your tests easier to read and maintain.

Putting It All Together

In your final project repository, you should end up with:

• A dedicated auth module or package, with:
• Routers for /auth/*.
• Service functions for token creation, password hashing, and email workflows.
• Dependencies for get_current_user, get_current_admin, etc.
• Database models for:
• User.
• Optional Role, Permission, UserRefreshToken, EmailVerificationToken, PasswordResetToken.
• Integration with:
• PostgreSQL for persistent auth data.
• Redis for rate limiting and token invalidation if you choose to implement it.
• Configuration:
• Strong secrets from environment variables.
• Token expiry and security settings controlled via config.
• Tests:
• Covering authentication and authorization flows and most critical error cases.

Keep the design clear and documented. The goal is not only to make your app secure, but also maintainable and understandable for someone reading your code or reviewing your project as part of a hiring process.

Views: 5