Week 19: Advanced Auth — OAuth2 Provider, API Keys & Multi-Tenancy

1. Running Your Own Authorization Server

Week 6 built the OAuth2 password flow directly into your own service — your API validated credentials and issued its own JWTs. Some platforms need to go one level deeper: issuing tokens to a genuinely separate first-party mobile app, a partner's third-party integration, or an internal service — all authenticating against a real authorization code grant, the flow a browser-based login actually uses, rather than the simplified password flow. The authlib library implements the full OAuth2 provider role on top of FastAPI.

from authlib.integrations.sqla_oauth2 import create_query_client_func
from authlib.oauth2.rfc6749 import grants

class AuthorizationCodeGrant(grants.AuthorizationCodeGrant):
    def save_authorization_code(self, code, request):
        auth_code = OAuth2AuthorizationCode(
            code=code,
            client_id=request.client.client_id,
            redirect_uri=request.redirect_uri,
            scope=request.scope,
            user_id=request.user.id,
        )
        db.add(auth_code)
        db.commit()

# a registered client, stored the same way a user record is
web_app = OAuth2Client(
    client_id="acme-web-app",
    client_secret=hash_secret("web-app-secret"),
    redirect_uris=["https://app.acme.com/callback"],
    scope="tasks:read tasks:write",
)

This is the same flow browser-based login always uses, except your server is now the one issuing the authorization code and, ultimately, the access token, rather than delegating to Google or GitHub the way Week 6's simpler setup did. Custom, application-specific scopes like tasks:read and tasks:write become possible in a way an external provider's fixed scope set never allowed, letting you express your own API's actual permission boundaries directly in the tokens you issue.

2. API Keys & the Client Credentials Grant

Every grant type in Week 6 and Section 1 assumes a human is present to log in. A scheduled Celery task, a webhook receiver, or a server calling your API with no user in the loop needs a different pattern entirely — there's no browser to redirect and no password to prompt for.

The client credentials grant is OAuth2's answer: the calling service authenticates directly with its own client ID and secret, no user or redirect involved, and receives an access token scoped to what that service is allowed to do.

curl -X POST https://auth.acme.com/oauth2/token \
  -u reporting-service:reporting-secret \
  -d "grant_type=client_credentials&scope=reports:generate"

# {"access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600}

For simpler internal or partner integrations where full OAuth2 is more machinery than the situation needs, a plain API key — a long random string, checked against a hashed value stored server-side, tied to an owning account and a set of permissions — is a legitimate, lighter-weight alternative:

from fastapi import Depends, HTTPException, Security
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

async def get_api_key_owner(
    raw_key: str = Security(api_key_header),
    db: AsyncSession = Depends(get_db),
) -> ApiKeyOwner:
    key = await api_keys.find_by_hash(db, hash_key(raw_key))
    if key is None or not key.is_active:
        raise HTTPException(status_code=401, detail="Invalid or inactive API key")
    return key.owner

The key's hash is what's stored and compared, exactly like Week 6's password hashing — a leaked database dump shouldn't hand out usable API keys any more than it should hand out usable passwords.

3. Multi-Tenant Data Isolation

Once a single deployment serves multiple customers ("tenants") from shared infrastructure, the single most important property the application has to guarantee is that Tenant A's request can never return Tenant B's data — not "usually doesn't," but structurally cannot. Three common strategies, in increasing order of isolation and operational cost:

• Shared schema, discriminator column — every table gets a tenant_id column, and every query filters by it. Cheapest to run and simplest to add a tenant to, but the isolation is only as strong as every single query remembering to filter correctly.
• Schema-per-tenant — one PostgreSQL schema per tenant, same database instance. Stronger isolation (a missing filter can't cross schemas as easily), but migrations and connection routing get meaningfully more complex as tenant count grows.
• Database-per-tenant — full physical isolation. Strongest guarantee, but the most operationally expensive: connection pooling, migrations, and backups now all multiply by tenant count.

For the common shared-schema approach, PostgreSQL's row-level security (RLS) enforces the tenant boundary directly in the database, rather than trusting every hand-written query to remember the WHERE tenant_id = ? clause:

ALTER TABLE task ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON task
    USING (tenant_id = current_setting('app.current_tenant_id')::int);

@app.middleware("http")
async def set_tenant_context(request: Request, call_next):
    tenant_id = get_tenant_from_auth(request)   # from the authenticated principal
    async with db_session() as session:
        await session.execute(
            text("SET app.current_tenant_id = :tid"), {"tid": tenant_id}
        )
        request.state.db = session
        response = await call_next(request)
    return response

With RLS enabled, every query issued through that connection for the rest of the request is automatically filtered by the current tenant setting at the database level — a developer writing a new repository method later can't accidentally forget the filter, because it isn't something they write per query at all; even a raw SQL query bypassing the ORM entirely is still constrained by the database itself.

4. Hands-on Exercise

5. Knowledge Check

Three quick questions. Expand each to check your answer.