Overview

Injectable FastAPI authentication and authorization against OIDC providers, built almost entirely on the Python standard library. armasec-lite is a dependency-minimal reimplementation of armasec 3.0.3 with the same public API: it validates bearer tokens against your identity provider's JWKS, checks scopes and issuer/audience claims, and plugs into a route with a single Depends(), all with three runtime dependencies instead of upstream's ten.

Quickstart

uv add armasec-lite

"""Secure a single route against one OIDC domain."""

import os

from armasec_lite import Armasec
from fastapi import Depends, FastAPI

app = FastAPI()
armasec = Armasec(
    domain=os.environ.get("ARMASEC_DOMAIN"),
    audience=os.environ.get("ARMASEC_AUDIENCE"),
)


@app.get("/stuff", dependencies=[Depends(armasec.lockdown("read:stuff"))])
async def check_access():
    return {"message": "Successfully authenticated!"}

More usage patterns, including multiple domains, match_keys, and the plugin system, are in examples/.

Why

Upstream armasec carries ten runtime dependencies. Two of them (pytest, respx) are test tools forced into every production install: armasec==3.0.3 declares pytest<9,>=6 and respx as runtime requirements, which is exactly the kind of constraint that made this project's own lockfile unsatisfiable when we tried to depend on upstream for benchmarking against a pytest>=9.1 toolchain. armasec-lite ships three runtime dependencies: fastapi, cryptography, and pydantic. pydantic is kept rather than dropped because fastapi requires it and imports it unconditionally, so it is installed and loaded in every deployment regardless of what this project declares; keeping it as a direct dependency preserves model_dump(), response_model=, and except pydantic.ValidationError for anyone migrating from upstream, instead of breaking all three for a saving of zero bytes.

Migrating from armasec

This is the complete list of behavior differences from upstream armasec 3.x. Migrating from 2.x is out of scope and untested; a 2.x consumer should upgrade to 3.x first and confirm their application works there.

Requires action from an integrator

Requires no action, listed so the API diff is complete

What is not included

The armasec CLI (device-code login, token cache) is not part of this package. It is already shipped as an extra upstream, it needs typer, rich, loguru, pendulum and pyperclip, and a stdlib rewrite of it is roughly as much work as the rest of this project combined. This library validates tokens; it does not issue, refresh, or otherwise participate in any OIDC client-side flow. A CLI can ship later as a separate distribution if there is demand for one.

Security

Signature verification delegates entirely to cryptography; nothing here hand-rolls RSA, ECDSA, EdDSA, or HMAC primitives. The verification order implemented in armasec_lite/jwt.py (structural checks, then the algorithm allowlist, then crit header validation, then signature verification with the JWK-type-versus-algorithm check inside it, and only afterward claim validation) is a security property, not an implementation detail, and is documented with its rationale directly in that module. Two orderings carry the security of the module: the algorithm is decided from the caller's allowlist before any key is touched, and nothing in the payload is read until the signature has verified. tests/unit/test_jwt_attacks.py is the enumeration of what is defended: alg: none, algorithm confusion, disallowed algorithms, kid mismatch, tampered headers and payloads, malformed ECDSA signature lengths, unrecognized crit entries, expired and not-yet-valid tokens, and audience/issuer mismatches.

Documentation

Full docs, including architecture, the request lifecycle, the caching and threading model, and the migration guide, are at https://docs.vantagecompute.ai/developer/armasec-lite/.