Metadata-Version: 2.4
Name: usso
Version: 0.28.6
Summary: A plug-and-play client for integrating universal single sign-on (SSO) with Python frameworks, enabling secure and seamless authentication across microservices.
Author-email: Mahdi Kiani <mahdikiany@gmail.com>
Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ussoio/usso-python
Project-URL: Bug Reports, https://github.com/ussoio/usso-python/issues
Project-URL: Funding, https://github.com/ussoio/usso-python
Project-URL: Say Thanks!, https://saythanks.io/to/mahdikiani
Project-URL: Source, https://github.com/ussoio/usso-python
Keywords: usso,sso,authentication,security,fastapi,django
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pydantic>=2
Requires-Dist: cryptography>=43.0.0
Requires-Dist: cachetools
Requires-Dist: singleton_package
Requires-Dist: json-advanced
Requires-Dist: httpx
Requires-Dist: usso-jwt>=0.1.15
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.65.0; extra == "fastapi"
Requires-Dist: uvicorn[standard]>=0.13.0; extra == "fastapi"
Provides-Extra: django
Requires-Dist: Django>=3.2; extra == "django"
Provides-Extra: dev
Requires-Dist: check-manifest; extra == "dev"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Provides-Extra: all
Requires-Dist: fastapi; extra == "all"
Requires-Dist: uvicorn; extra == "all"
Requires-Dist: django; extra == "all"
Requires-Dist: dev; extra == "all"
Requires-Dist: test; extra == "all"
Dynamic: license-file

# 🛡️ 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](https://github.com/ussoio/usso) — 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

```bash
pip install usso
````

With framework extras:

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

---

## 🚀 Quick Start (FastAPI)

```python
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:

```bash
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:

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

---

## 🧪 Testing

```bash
pytest
tox
```

---

## 🤝 Contributing

We welcome contributions! 

---

## 📝 License

MIT License © \[mahdikiani]

