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); table authz_assignment.

  • DynamoDbAssignmentStore: pip install 'auth-middleware[dynamodb]'; PynamoDB, single table (see DynamoDB Setup for Scoped Permissions).

Contract semantics (all stores)

  • get_assignment returns None when the scope or the principal does not exist.

  • A revoked assignment may be returned; the engine treats it as absent.

  • assign on an active assignment raises RevisionConflictError; on a revoked one it reactivates it with revision + 1.

  • Every write bumps revision by exactly 1; a stale expected_revision raises RevisionConflictError.

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.