ecc-auth 0.1.4

Shared Keycloak OIDC authentication SDK for ECC projects

ecc-auth

ecc-auth is a small shared authentication SDK for ECC Python services that integrate with Keycloak and FastAPI.

It provides:

• Keycloak configuration via KeycloakConfig
• Standard FastAPI auth routes via create_auth_router
• Current-user dependencies via get_current_user and get_current_user_optional
• JWT verification helpers via verify_access_token

Installation

Once published to PyPI:

pip install ecc-auth

Or with uv:

uv add ecc-auth

Quick Start

from fastapi import FastAPI

from ecc_auth import AuthSessionMiddleware, KeycloakConfig, create_auth_router, init_dependencies

app = FastAPI()
app.add_middleware(AuthSessionMiddleware)

config = KeycloakConfig(
    url="https://keycloak.example.com",
    realm="ecc",
    client_id="example-client",
    client_secret="example-secret",
    tls_insecure=False,
)

init_dependencies(config)
app.include_router(create_auth_router(config), prefix="/api/auth")

For apps served under a public sub-path, pass that path to the router so Keycloak receives the externally reachable callback URL:

app.include_router(
    create_auth_router(config, public_base_path="/deer-flow"),
    prefix="/api/auth",
)

Development

This repository is a single Python package repository. The package root, tests, and release metadata all live at the repository root.

Build the package locally:

uv build

Run tests:

uv run pytest

Callback Error Contract

When /api/auth/callback cannot complete, ecc-auth redirects back to the app origin with a stable ?error=<code> query parameter.

Current callback error codes:

• missing_state
• invalid_state
• missing_code
• csrf_mismatch
• missing_pkce
• token_exchange_failed
• callback_upstream_failed
• token_not_yet_valid
• token_validation_failed
• token_verification_unavailable
• user_sync_failed
• callback_failed

Consumer apps should map these codes to user-facing copy instead of exposing raw exception text.

Publishing

This repository includes a GitHub Actions workflow at .github/workflows/publish-python.yml.

Recommended release flow:

1. Bump version in pyproject.toml.
2. Commit and push the change.
3. Create a GitHub release.
4. Let the workflow build and publish the package to PyPI.

Before the first release, configure a Trusted Publisher for this repository in PyPI and point it at:

• Repository owner: early-chinese-civilization
• Repository name: ecc-auth
• Workflow file: .github/workflows/publish-python.yml
• Environment name: pypi