Assignment Stores
A store is anything implementing the AssignmentStore port (get_assignment,
list_assignments); the optional AssignmentAdmin port adds assign, change_role,
revoke and list_for_scope. The backend is injected at startup, never read from the
environment by the library.
InMemoryAssignmentStore: no extra; tests, examples and the reference implementation.SqlAssignmentStore:pip install 'auth-middleware[postgres]'or[mysql]([sqlalchemy]installs both drivers); tableauthz_assignment.DynamoDbAssignmentStore:pip install 'auth-middleware[dynamodb]'; PynamoDB, single table (see DynamoDB Setup for Scoped Permissions).
Contract semantics (all stores)
get_assignmentreturnsNonewhen the scope or the principal does not exist.A revoked assignment may be returned; the engine treats it as absent.
assignon an active assignment raisesRevisionConflictError; on a revoked one it reactivates it withrevision + 1.Every write bumps
revisionby exactly 1; a staleexpected_revisionraisesRevisionConflictError.
SQLAlchemy
SqlAssignmentStore accepts an async_sessionmaker (short session per call), a callable
returning an async context manager, or an already open AsyncSession. With an open session the
store never commits, rolls back or closes it: reads and writes happen in the caller’s transaction.
before_query(session, scope) runs before every statement; that is where an application binds
row-level security. The table comes from an Alembic revision (a3f1c9d2b7e4) or from
auth_middleware.authz.stores.sql_models.metadata included in your own target_metadata.
Per-request store (sharing the request’s session)
Authz.build(store_factory=...) calls the factory once per request, lazily, when the guard runs.
Sketch (the same shape is exercised by tests/authz/test_sql_store_unit.py and the PostgreSQL
RLS test in tests/authz/integration/):
async def store_for(request):
session = request.state.session # opened by your own dependency
async def bind_rls(session, scope):
if scope is not None:
await session.execute(
text("SELECT set_config('app.scope_id', :id, true)"), {"id": scope.id}
)
return SqlAssignmentStore(session, before_query=bind_rls)
Authz.build(catalog=catalog, store_factory=store_for).install(app)
FastAPI resolves the sub-dependencies of a route in declaration order: a dependency that must run before the check (e.g. one that opens the session) has to be declared before the guard.
DynamoDB
DynamoDbAssignmentStore(table_name=...) uses PynamoDB, which is synchronous: each call runs in a
worker thread. get_assignment uses consistent reads by default (a just-revoked principal must not be
admitted); list_assignments uses the GSI and may lag. Throttling that survives retries raises
StoreUnavailableError.
Tested engines
The same contract suite runs against PostgreSQL 17 and MySQL 8 (SqlAssignmentStore) and DynamoDB
(DynamoDbAssignmentStore). make test-floci starts Floci with
testcontainers; it emulates DynamoDB and starts real PostgreSQL and MySQL containers through its RDS emulation
(Docker required). On MySQL the identifier columns use utf8mb4_bin, because its default collations would treat
Abc and abc as the same principal.
Writing your own adapter
Implement the two read methods over your own tables and subclass the shipped suite:
from auth_middleware.authz.testing import AssignmentStoreContract
class TestMyStore(AssignmentStoreContract):
supports_attributes = False # if your store cannot keep attributes
@asynccontextmanager
async def make_store(self):
yield MyStore(...)
The suite covers twelve behaviours, including 20 concurrent assign calls with exactly one winner.