🛡️ USSO Python Client SDK

The USSO Python Client SDK (usso) provides a universal, secure JWT authentication layer for Python microservices and web frameworks.
It’s designed to integrate seamlessly with the USSO Identity Platform — or any standards-compliant token issuer.

🔗 Relationship to the USSO Platform

This SDK is the official verification client for the USSO identity service, which provides multi-tenant authentication, RBAC, token flows, and more.
You can use the SDK with:

Self-hosted USSO via Docker
Any identity provider that issues signed JWTs (with proper config)

✨ Features

✅ Token verification for EdDSA, RS256, HS256, and more
✅ Claim validation (exp, nbf, aud, iss)
✅ Remote JWK support for key rotation
✅ Typed payload parsing via UserData (Pydantic)
✅ Token extraction from:
- Authorization header
- Cookies
- Custom headers
✅ FastAPI integration with dependency injection
✅ Django middleware for request-based user resolution
🧪 90% tested with pytest and tox

📦 Installation

pip install usso

With framework extras:

pip install "usso[fastapi]"     # for FastAPI integration
pip install "usso[django]"      # for Django integration

🚀 Quick Start (FastAPI)

from usso.fastapi.integration import get_authenticator
from usso.schemas import JWTConfig, JWTHeaderConfig, UserData
from usso.jwt.enums import Algorithm

config = JWTConfig(
    key="your-ed25519-public-key",
    issuer="https://sso.example.com",
    audience="api.example.com",
    type=Algorithm.EdDSA,
    header=JWTHeaderConfig(type="Authorization"),
)

authenticator = get_authenticator(config)


@app.get("/me")
def get_me(user: UserData = Depends(authenticator)):
    return {"user_id": user.sub, "roles": user.roles}

🧱 Project Structure

src/usso/
├── fastapi/            # FastAPI adapter
├── django/             # Django middleware
├── jwt/                # Core JWT logic and algorithms
├── session/            # Stateless session support
├── models/             # JWTConfig, UserData, etc.
├── exceptions/         # Shared exceptions
├── authenticator.py    # High-level API (token + user resolution)

🐳 Integrate with USSO (Docker)

Run your own identity provider:

docker run -p 8000:8000 ghcr.io/ussoio/usso:latest

Then configure your app to verify tokens issued by this service, using its public JWKS endpoint:

JWTConfig(
    jwks_url="http://localhost:8000/.well-known/jwks.json",
    ...
)

🧪 Testing

pytest
tox

USSO Lite for standalone FastAPI applications

Install the local identity dependencies and mount the router:

pip install "usso[lite,fastapi]"

from fastapi import FastAPI
from usso.lite import EXCEPTION_HANDLERS, LiteConfig, create_lite_router

app = FastAPI()
config = LiteConfig(
    database_url="sqlite+aiosqlite:///./identity.db",
    issuer="https://api.example.com",
    audience="api.example.com",
    otp_sender=send_otp,  # async (identifier_type, identifier, code)
)
app.include_router(create_lite_router(config))
for exception, handler in EXCEPTION_HANDLERS.items():
    app.add_exception_handler(exception, handler)

Lite emits the same UserData-compatible claims as USSO and publishes its public signing key at /.well-known/jwks.json. A service can therefore move to full USSO by changing its issuer/JWKS configuration without changing its authorization code.

Security defaults:

public registration cannot assign roles or scopes;
user-management routes require admin:usso/lite/users (or a broader USSO scope);
OTP values are never returned by HTTP unless expose_otp_in_response=True is explicitly enabled for local development;
refresh tokens are single-use and sessions are checked on every local authenticated request;
login, registration, and OTP requests are rate-limited.

For initial provisioning, pass a trusted FastAPI dependency as admin_dependency= (for example, a deployment-only API-key dependency), use POST /users to create the first scoped administrator, then remove that bootstrap dependency. Do not grant the admin scope through default_scopes, because defaults apply to every public registration.

🤝 Contributing

We welcome contributions!

📝 License

MIT License © [mahdikiani]

Metadata

Release files for usso 0.33.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for usso 0.33.4
File	Size	Uploaded
usso-0.33.4.tar.gz	200.3 kB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for usso 0.33.4
File	Interpreter	ABI	Platform	Reset
usso-0.33.4-py3-none-any.whl 76.6 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 276.9 kB

Release files / usso-0.33.4.tar.gz

Download URL	usso-0.33.4.tar.gz
Size	200.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`fbb86dfd7c911ce762c21dadba4a36b73ed86ca9db35508480f0d47339292648`
BLAKE2b-256 checksum How to use checksums	`278cb55e5f17a5c70e6735abe4d3ce555fe03228863db5aac20993781bf615fd`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / usso-0.33.4-py3-none-any.whl

Download URL	usso-0.33.4-py3-none-any.whl
Size	76.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`965a0c003adda98c2b683d0d4b77b0708c3121ba3e9a7cc22b955c817046fa55`
BLAKE2b-256 checksum How to use checksums	`63242eae2552956b721ed33b0a6d72856a4dac553176d94d097acdef3026a1e8`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`