altissimo-auth
Reusable, framework-agnostic authentication library for Python applications.
Features
- 🔑 API Key authentication with pluggable storage backends
- 🔥 Firebase ID token verification and user record resolution
- 🌐 Google OAuth2 ID token verification
- 🛡️ Google IAP header extraction
- 🔒 OIDC service-to-service authentication with configurable caller policies
- 🪝 Webhook signature verification (Stripe included, extensible via protocol)
- ⚡ FastAPI adapter with
Depends()wrappers and structured telemetry - 🥷 Django Ninja adapter with native auth classes
- 🧪 Flask adapter for server-side Google OAuth2 Authorization Code flow
- 🌊 Auth Cascade for multi-method authentication fallback
- 🧅 Layered Auth for required gate + optional identity (BFF pattern)
- 📐 Typed — full type annotations with
py.typedPEP 561 marker - 🧪 Testing stubs — drop-in test helpers that eliminate ~100 lines of conftest boilerplate
Requirements
- Python 3.11+
Installation
Published on PyPI as altissimo-auth;
the import name is altissimo.auth.
pip install "altissimo-auth[fastapi]" # core + FastAPI adapter
pip install "altissimo-auth[ninja]" # core + Django Ninja adapter
pip install "altissimo-auth[flask]" # core + Flask OAuth2 adapter
pip install "altissimo-auth[firebase]" # core + Firebase provider
pip install "altissimo-auth[google]" # core + Google OAuth2/OIDC providers
pip install "altissimo-auth[all]" # everything
Quick Start
FastAPI
from typing import Annotated
from fastapi import Depends, FastAPI
from altissimo.auth import FirebaseUser
from altissimo.auth.fastapi import Auth, configure
from altissimo.auth.service import AuthService
app = FastAPI()
# Configure once at startup
configure(AuthService(api_key_backend=my_backend))
# Route-level guard
@app.get("/items", dependencies=[Depends(Auth.validate_api_key)])
async def list_items():
...
# Parameter injection
@app.get("/me")
async def get_me(
user: Annotated[FirebaseUser, Depends(Auth.validate_firebase_user)],
):
return {"uid": user.uid, "email": user.email}
Django Ninja
from ninja import NinjaAPI
from altissimo.auth.cascade import AuthCascade
from altissimo.auth.ninja import ApiKeyAuth, FirebaseAuth, OIDCAuth, configure
from altissimo.auth.service import AuthService
api = NinjaAPI()
# Configure once at startup
configure(AuthService(api_key_backend=my_backend))
# Route-level guard
@api.get("/items", auth=ApiKeyAuth())
def list_items(request):
...
# Cascading Auth (Multi-Method Fallback)
cascade = AuthCascade([FirebaseAuth(), ApiKeyAuth()])
@api.get("/me", auth=cascade)
def get_me(request):
user = request.auth # Will be FirebaseUser or APIKeyRecord
...
# Layered Auth (Required Gate + Optional Identity)
from altissimo.auth.ninja import LayeredAuth
public_auth = LayeredAuth(
gate=ApiKeyAuth(), # MUST pass — 401 if it fails
identity=FirebaseAuth(), # OPTIONAL — enriches request.auth if present
)
@api.get("/communities", auth=public_auth)
def list_communities(request):
user = request.auth # FirebaseUser | None
api_key = request.gate_auth # APIKeyRecord (always available)
...
Flask (Server-Side Google OAuth2)
from flask import Flask, g
from altissimo.auth.flask import OAuth2FlowManager
app = Flask(__name__)
app.secret_key = "super-secret"
auth = OAuth2FlowManager(
client_secrets_file="client_secret.json",
scopes=["openid", "email", "profile"],
redirect_uri_endpoint="oauth2_callback",
hosted_domain="mycompany.com" # Optional: restrict to domain
)
@app.route("/login")
def login():
return auth.login_redirect()
@app.route("/oauth2_callback")
def oauth2_callback():
user_info = auth.handle_callback()
return f"Logged in as {user_info['email']}"
@app.route("/logout")
def logout():
auth.logout()
return "Logged out"
@app.route("/protected")
@auth.require_auth
def protected():
return f"Hello, {g.user.email}" # g.user is populated by require_auth
Testing
# conftest.py — runs before Django is configured
from altissimo.auth.testing import install_test_modules, StubApiKeyAuth
class MyApiKeyAuth(StubApiKeyAuth):
def authenticate(self, request, key):
api_key_id = key or request.GET.get("api_key")
if not api_key_id:
return None
return MyBackend().get_key(api_key_id)
install_test_modules(api_key_auth_class=MyApiKeyAuth)
# Now configure Django and import your app normally...
OIDC Service-to-Service
from altissimo.auth.fastapi import Auth
from altissimo.auth.providers.oidc import OIDCPolicy
policy = OIDCPolicy(
allowed_callers={
"dev": ["sa@my-project-dev.iam.gserviceaccount.com"],
"prod": ["sa@my-project-prod.iam.gserviceaccount.com"],
},
valid_audiences={
"dev": ["https://api-dev.run.app"],
"prod": ["https://api-prod.run.app"],
},
project_sa_suffix="@my-project-{env}.iam.gserviceaccount.com",
team_domains=["mycompany.com"],
)
verify_caller = Auth.create_oidc_dependency(policy)
@app.post("/callback", dependencies=[Depends(verify_caller)])
async def handle_callback():
...
Architecture
altissimo.auth
├── core/ # Framework-agnostic models, exceptions, policies
├── providers/ # Token/key verification (API key, Firebase, Google, OIDC, IAP, webhooks)
├── service.py # AuthService orchestration layer
├── fastapi/ # FastAPI Depends() wrappers
└── ninja/ # Django Ninja auth classes
Provider → Service → Adapter Pattern
- Providers contain the actual auth logic (token verification, key lookup)
- AuthService wires providers + policies together
- Adapters are thin framework-specific wrappers that delegate to AuthService
Pluggable Backends
API key storage and webhook verification are abstracted via Python Protocols:
from altissimo.auth.providers import APIKeyBackend
class MyKeyBackend:
"""Implement the APIKeyBackend protocol with your storage."""
def get_key(self, key_id: str) -> APIKeyRecord | None:
return db.query(APIKey).filter_by(id=key_id).first()
Development
# Install all dependencies
poetry sync
# Run tests
poetry run pytest
# Run tests with coverage
poetry run pytest --cov=altissimo --cov-report=term-missing
# Run linters
poetry run ruff check .
poetry run ruff format --check .
See CONTRIBUTING.md for detailed development guidelines.
Changelog
See CHANGELOG.md for version history.
Security
For reporting security vulnerabilities, see SECURITY.md.
License
Apache License 2.0 — see LICENSE for details.
Metadata
Release files for altissimo-auth 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| altissimo_auth-1.1.0.tar.gz | 29.4 kB | With provenance | Details for altissimo_auth-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| altissimo_auth-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for altissimo_auth-1.1.0-py3-none-any.whl |
Total release size: 65.4 kB
Release files / altissimo_auth-1.1.0.tar.gz
| Download URL | altissimo_auth-1.1.0.tar.gz |
|---|---|
| Size | 29.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31f52754e92643ce21b2829ab5a51c7c2132e02796cb309a2bc821394e42aaff
|
|
BLAKE2b-256 checksum How to use checksums |
dac5003b9c544e92480da509ad80a69585f1a59cd14ce246da3d9e99514920e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / altissimo_auth-1.1.0-py3-none-any.whl
| Download URL | altissimo_auth-1.1.0-py3-none-any.whl |
|---|---|
| Size | 36.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
250fe078a2aeed0f9ff71c4de66049e15990575bea24188aa3ab2b196e06f610
|
|
BLAKE2b-256 checksum How to use checksums |
0c8faeee5b3602221e4ecb2e56ef076970a6b72c7d7bb414aedb6e51ca4ced4f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for altissimo-auth 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for altissimo_auth-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.