🛡️ 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:
Authorizationheader- Cookies
- Custom headers
- ✅ FastAPI integration with dependency injection
- ✅ Django middleware for request-based user resolution
- 🧪 90% tested with
pytestandtox
📦 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=Trueis 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]
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file usso-0.32.9.tar.gz.
File metadata
- Download URL: usso-0.32.9.tar.gz
- Upload date:
- Size: 191.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3f0e3e8c9d89b5c0dde7145c8d963a7fa6b46986dae7e6478bf5910133aa977f
|
|
| MD5 |
8c10657498d4ce1572a6695482eb73d8
|
|
| BLAKE2b-256 |
83c75e067d7ba75e930d40c3929fd360419849693e5d8f7b7a87d988c113eeec
|
File details
Details for the file usso-0.32.9-py3-none-any.whl.
File metadata
- Download URL: usso-0.32.9-py3-none-any.whl
- Upload date:
- Size: 70.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
66d24127ea9dcb816594cf306b2ea19a99a9ec9ade70b6ac0cbdb8c012df187a
|
|
| MD5 |
858529aaf24865696b531b542e07e69d
|
|
| BLAKE2b-256 |
085ef7ea4eec9a0f9907622da58af42ba96a9e177ac76a15ab3c9b04d3872397
|
