Skip to main content

altissimo-auth

CI Python License Code style: ruff

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.typed PEP 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)

Source distribution for altissimo-auth 1.1.0
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)

Table of built distributions (wheels) for altissimo-auth 1.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page