Authentication

Controlling who can do what

Concepts

Authentication verifies who you are (you know the password)
- authorization decides what you are allowed to do (you may write but not delete)
- the two concepts are distinct, even though they are often implemented together
HTTP Basic Auth sends the username and password base64-encoded in a request header on every request
- simple and supported everywhere
- only safe over HTTPS because base64 is not encryption
A session cookie stores a random token in the browser; the server maps the token to an authenticated user
- the user only enters their password once per session rather than on every request
Passwords must never be stored in plaintext
- hash them with a slow algorithm designed for passwords (bcrypt, Argon2)
- makes brute-forcing impractical even if the hash database is stolen
A Litestar guard is a function that runs before a handler and can raise NotAuthorizedException to return a 401 or 403 response before any application code executes

Why authentication?

Read-only access to published results can be public, but uploading and deleting records should require a login
The threat model for a research tool vs. a public-facing web app

HTTP Basic Auth

The simplest approach: a username and password in the request header
How browsers prompt for credentials
What Litestar's guard mechanism provides, and how to plug Basic Auth into it

Session-based login

A login form, a POST route that validates credentials, and a session cookie that persists across requests
Why plaintext passwords in a config file are not acceptable even for an internal tool, and how to use hashed passwords instead

Protecting routes

Applying the authentication guard to upload and delete routes while leaving the read-only table and chart routes public
Testing that an unauthenticated request is rejected with 401

What this does not cover

Multi-user accounts, role-based access control, OAuth, and token-based APIs
When each of those becomes necessary and where to learn more

Check for Understanding

What is the difference between authentication and authorization?

Authentication answers "who are you?" by verifying a claimed identity (username + password, certificate, token). Authorization answers "are you allowed to do this?" by checking the authenticated identity against a set of permissions. A logged-in user is authenticated; whether they can delete a record depends on authorization. You can have authentication without authorization (everyone who logs in can do everything) or, less commonly, coarse authorization without strong authentication.

Why is it unsafe to store passwords in a config file as plaintext, even for an internal research tool?

Config files are often committed to version control, shared with collaborators, backed up to cloud storage, or read by anyone who has shell access to the server. A plaintext password in a file is readable by anyone who can read the file. Even if the risk seems low today, credentials tend to outlive the context in which they were created, and people reuse passwords across systems. Hashing protects against these scenarios.

What does "hashing" a password mean, and why does using sha256 alone not provide adequate protection?

Hashing transforms a password into a fixed-length string that cannot be reversed to recover the original. sha256 is fast—designed for checksums, not passwords—which means an attacker with the hash database can test billions of guesses per second. Password hashing algorithms like bcrypt or Argon2 are deliberately slow and can be tuned to make each guess take milliseconds, reducing an attacker's throughput from billions per second to thousands per second.

If a Litestar guard returns a 401, what does the browser typically do next?

For HTTP Basic Auth, the browser displays a built-in login dialog prompting for a username and password. If the server also sends a WWW-Authenticate header specifying the realm and scheme. For session-based auth, a 401 typically triggers a JavaScript redirect to the login page (or the server itself redirects with a 302). The exact behavior depends on how the guard and the client are implemented.

Exercises

Add a logout route

Add a POST /logout route that clears the session cookie and redirects to the home page. Write a pytest test that: (1) logs in, (2) makes a successful request to a protected route, (3) calls the logout route, (4) makes the same request to the protected route again, and (5) asserts the response is 401.

Test the guard

Write two pytest tests for a protected route: one that sends a request with no credentials and asserts the response is 401, and one that sends correct credentials and asserts the response is 200. Use create_test_client and pass credentials in the request headers; do not rely on a running server.

Audit the threat model

List the three most realistic threats to a research tool deployed on a university server (for example: a disgruntled collaborator, accidental exposure of the URL, a compromised user account). For each threat, describe whether the authentication scheme implemented in this lesson addresses it, partially addresses it, or does not address it. Suggest one additional measure that would reduce each remaining risk.

Compare authentication approaches

Ask the LLM to explain the differences between HTTP Basic Auth, session-based login, and API token authentication. Evaluate the explanation: is it accurate? Does it explain when each approach is appropriate? Add a sentence for anything the LLM omitted or got wrong.