Auth and sessions¶
admin = HxAdmin(
app,
session=get_session, # dependency yielding an AsyncSession
auth=current_admin_user, # dependency returning the user, or raising HTTPException
prefix="/admin",
login_url="/login", # optional
logout_url="/logout", # optional; Log out button at the bottom of the sidebar
trusted_origins=(), # optional; other origins allowed to send writes
)
Sessions¶
session is any FastAPI dependency that yields or returns an AsyncSession, such as get_session in Getting started. hxadmin uses one session per request, commits after a successful save, delete or action, and rolls back on errors. hxadmin re-queries after commits, so expire_on_commit=True sessionmakers work.
FastAPI resolves a dependency once per request, so when your auth (or a custom page) also depends on get_session, it gets the very same session hxadmin uses. Rows your auth loads can then be used in on_save and actions like any other row of the request; after its own commits and rollbacks, hxadmin reloads the user auth returned when it is such a row, so hooks can keep reading it. A custom page handler gets the same session too, but hxadmin does not commit for it; see Custom pages.
Auth¶
auth runs on every admin request. Its return value is available as request.state.hxadmin_user and as user in templates. The user panel at the bottom of the sidebar shows user.name (an attribute or a mapping key) when it is set, otherwise str(user), with initials derived from it. Any return value works: None or a bool (an auth that only answers "allowed") shows a generic avatar with no name.
To deny access, raise HTTPException(status.HTTP_401_UNAUTHORIZED) or HTTPException(status.HTTP_403_FORBIDDEN) (status is fastapi.status). With login_url set, a 401 or 403 raised by auth sends the browser to the login page (a 303, or HX-Redirect for htmx requests). Once auth has returned a user, later 401s and 403s (is_accessible, custom pages, the cross-site check) render the error page instead, as do all of them without login_url, keeping the exception's headers.
Example: HTTP Basic against the users table¶
A complete auth for the docs models that needs nothing beyond FastAPI and the standard library. The browser asks for an e-mail and password, which are checked against User.password_hash. It returns the signed-in User row, which the other pages' examples rely on.
# myapp/auth.py
import hashlib
import hmac
import os
from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from myapp.db import get_session
from myapp.models import User
basic = HTTPBasic(realm="Admin")
def hash_password(password: str) -> str:
salt = os.urandom(16)
digest = hashlib.scrypt(password.encode(), salt=salt, n=2**14, r=8, p=1)
return f"{salt.hex()}${digest.hex()}"
def verify_password(password: str, stored: str) -> bool:
salt, _, digest = stored.partition("$")
candidate = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt), n=2**14, r=8, p=1)
return hmac.compare_digest(candidate.hex(), digest)
async def current_admin_user(
credentials: Annotated[HTTPBasicCredentials, Depends(basic)],
session: Annotated[AsyncSession, Depends(get_session)],
) -> User:
user = await session.scalar(select(User).where(User.email == credentials.username))
if (
user is None
or not user.active
or user.password_hash is None
or not verify_password(credentials.password, user.password_hash)
):
raise HTTPException(
status.HTTP_401_UNAUTHORIZED,
"Wrong e-mail or password.",
headers={"WWW-Authenticate": "Basic"},
)
return user
Create the first account from a script or a shell, since the admin cannot be opened without one:
async with sessionmaker() as session:
session.add(
User(
name="Ada",
email="ada@example.com",
password_hash=hash_password("..."),
is_superuser=True,
)
)
await session.commit()
Notes on this example:
- The
Userrow depends onget_session, so it belongs to the request's session (see Sessions). A custom page that commits and then renders with anexpire_on_commit=Truesessionmaker mustawait session.refresh(user)itself, since hxadmin does not handle custom pages' commits. - Every active user with a password can open the admin;
is_superuseronly matters where your views check it (see Views and Actions). If the users table also holds customers, add anis_staffcolumn and check it here. - The
WWW-Authenticateheader makes the browser show its login prompt again after a wrong password. Do not setlogin_urlwith HTTP Basic: hxadmin would redirect instead of letting the browser prompt. - Browsers keep Basic credentials until they quit, so there is no real log out; leave
logout_urlunset. - Basic sends the password with every request: serve the admin over HTTPS only.
Example: your app's own login¶
When your application already signs users in with a cookie session, auth reads that session and hxadmin sends signed-out visitors to your login page. With Starlette's SessionMiddleware (it needs itsdangerous):
import os
from typing import Annotated
from fastapi import Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from starlette.middleware.sessions import SessionMiddleware
from starlette.requests import Request
from myapp.db import get_session
from myapp.models import User
app.add_middleware(SessionMiddleware, secret_key=os.environ["SESSION_SECRET"], https_only=True)
async def current_admin_user(
request: Request, session: Annotated[AsyncSession, Depends(get_session)]
) -> User:
user_id = request.session.get("user_id")
user = await session.get(User, user_id) if user_id is not None else None
if user is None or not user.active:
raise HTTPException(status.HTTP_401_UNAUTHORIZED)
return user
admin = HxAdmin(
app, session=get_session, auth=current_admin_user, login_url="/login", logout_url="/logout"
)
The admin is mounted inside app, so middleware added to app runs for admin requests too and request.session works there. /login and /logout are your application's routes, outside the admin. The Log out button in the sidebar is a plain link, so /logout must answer GET.
The sign-in page¶
If your app has no login page of its own, admin.render_login() renders one in the admin's style (light and dark, logo_url and title, no sidebar). Its form posts username and password to the current path. Continuing the module above, with verify_password from the HTTP Basic example:
from fastapi import status
from fastapi.responses import HTMLResponse, RedirectResponse
from sqlalchemy import select
@app.get("/login", response_model=None)
async def login_form(request: Request) -> HTMLResponse:
return admin.render_login(request)
@app.post("/login", response_model=None)
async def login(
request: Request, session: Annotated[AsyncSession, Depends(get_session)]
) -> HTMLResponse | RedirectResponse:
form = await request.form()
email = str(form.get("username", "")).strip()
password = str(form.get("password", ""))
user = await session.scalar(select(User).where(User.email == email))
if (
user is None
or not user.active
or user.password_hash is None
or not verify_password(password, user.password_hash)
):
return admin.render_login(
request,
error="Wrong e-mail or password.",
username=email,
status_code=status.HTTP_401_UNAUTHORIZED,
)
request.session.clear()
request.session["user_id"] = user.id
return RedirectResponse("/admin/", status_code=status.HTTP_303_SEE_OTHER)
@app.get("/logout")
async def logout(request: Request) -> RedirectResponse:
request.session.clear()
return RedirectResponse("/login", status_code=status.HTTP_303_SEE_OTHER)
render_login takes, all optional and keyword-only:
| Argument | Default | |
|---|---|---|
error |
None |
Shown above the form, for a failed attempt |
username |
"" |
Prefills the first field (the submitted value after an error) |
username_label |
"E-mail" |
Label of the first field, e.g. "Username" |
note |
None |
A line of text under the form, e.g. who to ask for an account |
action |
the current path | Where the form posts |
status_code |
200 |
401 suits a failed attempt |
verify_password is the one from the HTTP Basic example above. Clearing the session before setting user_id drops anything an attacker planted in it before sign-in. To change the page, put your own hxadmin/login.html in templates_dir (it can extend hxadmin-builtin/login.html, see Templates); it receives the arguments above plus admin, request and admin_root (the admin's URL prefix, for {{ admin_root }}/static/hxadmin.css).
Both demo apps (make demo, make demo/tables) sign in this way.
Per view, is_accessible(request) and is_visible(request) narrow access further. Per action, is_action_allowed(request, name) does; see Actions.
Cross-site requests¶
hxadmin refuses state-changing requests (POST, PUT, PATCH, DELETE) that a browser sends from another origin, so another site cannot make a signed-in admin's browser create, edit, delete or run an action. This covers every admin route, custom pages included, whatever your auth uses (cookies included), and needs no tokens in your templates.
- Browsers send
Sec-Fetch-Site; a write passes when it issame-origin(ornone, a request the user started directly).same-siteis refused too, so a sibling subdomain cannot write. - Browsers too old for
Sec-Fetch-SitesendOrigin, which must match the request'sHost. - Requests with neither header do not come from a browser (scripts, tests, server-to-server calls) and pass;
authstill applies. GET,HEADandOPTIONSalways pass, which is whymethod="GET"actions must not change data (see Actions).
A refused request gets a 403 ("Cross-origin request blocked.": an error page, or an error toast for htmx) and a warning on the hxadmin logger naming the method, path, Origin and Sec-Fetch-Site.
To accept writes from another origin you control, such as a separate frontend, list it:
Each entry is a bare origin, scheme://host[:port], with no path; anything else raises ValueError.
Behind a reverse proxy, browsers that only send Origin need the proxy to pass the public Host header through (e.g. nginx proxy_set_header Host $host;). Current browsers send Sec-Fetch-Site, which does not depend on the proxy.