| Name | usso JSON |
| Version |
0.28.38
JSON |
| download |
| home_page | None |
| Summary | A plug-and-play client for integrating universal single sign-on (SSO) with Python frameworks, enabling secure and seamless authentication across microservices. |
| upload_time | 2025-07-27 16:06:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
usso
sso
authentication
security
fastapi
django
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🛡️ 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(
jwks_url="http://localhost:8000/.well-known/jwks.json",
...
)
```
---
## 🧪 Testing
```bash
pytest
tox
```
---
## 🤝 Contributing
We welcome contributions!
---
## 📝 License
MIT License © \[mahdikiani]
Raw data
{
"_id": null,
"home_page": null,
"name": "usso",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Mahdi Kiani <mahdikiany@gmail.com>",
"keywords": "usso, sso, authentication, security, fastapi, django",
"author": null,
"author_email": "Mahdi Kiani <mahdikiany@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/29/e2/9a2e021a3fbfd440b7d159248b3eba5104e7b5efc402a909698ae46c971a/usso-0.28.38.tar.gz",
"platform": null,
"description": "# \ud83d\udee1\ufe0f USSO Python Client SDK\n\nThe **USSO Python Client SDK** (`usso`) provides a universal, secure JWT authentication layer for Python microservices and web frameworks. \nIt\u2019s designed to integrate seamlessly with the [USSO Identity Platform](https://github.com/ussoio/usso) \u2014 or any standards-compliant token issuer.\n\n---\n\n## \ud83d\udd17 Relationship to the USSO Platform\n\nThis SDK is the official verification client for the **USSO** identity service, which provides multi-tenant authentication, RBAC, token flows, and more. \nYou can use the SDK with:\n- Self-hosted USSO via Docker\n- Any identity provider that issues signed JWTs (with proper config)\n\n---\n\n## \u2728 Features\n\n- \u2705 **Token verification** for EdDSA, RS256, HS256, and more\n- \u2705 **Claim validation** (`exp`, `nbf`, `aud`, `iss`)\n- \u2705 **Remote JWK support** for key rotation\n- \u2705 **Typed payload parsing** via `UserData` (Pydantic)\n- \u2705 **Token extraction** from:\n - `Authorization` header\n - Cookies\n - Custom headers\n- \u2705 **FastAPI integration** with dependency injection\n- \u2705 **Django middleware** for request-based user resolution\n- \ud83e\uddea 90% tested with `pytest` and `tox`\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install usso\n````\n\nWith framework extras:\n\n```bash\npip install \"usso[fastapi]\" # for FastAPI integration\npip install \"usso[django]\" # for Django integration\n```\n\n---\n\n## \ud83d\ude80 Quick Start (FastAPI)\n\n```python\nfrom usso.fastapi.integration import get_authenticator\nfrom usso.schemas import JWTConfig, JWTHeaderConfig, UserData\nfrom usso.jwt.enums import Algorithm\n\nconfig = JWTConfig(\n key=\"your-ed25519-public-key\",\n issuer=\"https://sso.example.com\",\n audience=\"api.example.com\",\n type=Algorithm.EdDSA,\n header=JWTHeaderConfig(type=\"Authorization\")\n)\n\nauthenticator = get_authenticator(config)\n\n@app.get(\"/me\")\ndef get_me(user: UserData = Depends(authenticator)):\n return {\"user_id\": user.sub, \"roles\": user.roles}\n```\n\n---\n\n## \ud83e\uddf1 Project Structure\n\n```\nsrc/usso/\n\u251c\u2500\u2500 fastapi/ # FastAPI adapter\n\u251c\u2500\u2500 django/ # Django middleware\n\u251c\u2500\u2500 jwt/ # Core JWT logic and algorithms\n\u251c\u2500\u2500 session/ # Stateless session support\n\u251c\u2500\u2500 models/ # JWTConfig, UserData, etc.\n\u251c\u2500\u2500 exceptions/ # Shared exceptions\n\u251c\u2500\u2500 authenticator.py # High-level API (token + user resolution)\n```\n\n---\n\n## \ud83d\udc33 Integrate with USSO (Docker)\n\nRun your own identity provider:\n\n```bash\ndocker run -p 8000:8000 ghcr.io/ussoio/usso:latest\n```\n\nThen configure your app to verify tokens issued by this service, using its public JWKS endpoint:\n\n```python\nJWTConfig(\n jwks_url=\"http://localhost:8000/.well-known/jwks.json\",\n ...\n)\n```\n\n---\n\n## \ud83e\uddea Testing\n\n```bash\npytest\ntox\n```\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! \n\n---\n\n## \ud83d\udcdd License\n\nMIT License \u00a9 \\[mahdikiani]\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A plug-and-play client for integrating universal single sign-on (SSO) with Python frameworks, enabling secure and seamless authentication across microservices.",
"version": "0.28.38",
"project_urls": {
"Bug Reports": "https://github.com/ussoio/usso-python/issues",
"Funding": "https://github.com/ussoio/usso-python",
"Homepage": "https://github.com/ussoio/usso-python",
"Say Thanks!": "https://saythanks.io/to/mahdikiani",
"Source": "https://github.com/ussoio/usso-python"
},
"split_keywords": [
"usso",
" sso",
" authentication",
" security",
" fastapi",
" django"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6c3cb5414a9e2fb585ecbc41ea40a55053de43834e673c29411c63cacab8454b",
"md5": "a61f19385261dd0f4d247648177d7076",
"sha256": "bf9a8a39ba87603e6569858a37df67eea067849e6d202e9b836885d516e1b23f"
},
"downloads": -1,
"filename": "usso-0.28.38-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a61f19385261dd0f4d247648177d7076",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 20134,
"upload_time": "2025-07-27T16:06:34",
"upload_time_iso_8601": "2025-07-27T16:06:34.883060Z",
"url": "https://files.pythonhosted.org/packages/6c/3c/b5414a9e2fb585ecbc41ea40a55053de43834e673c29411c63cacab8454b/usso-0.28.38-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "29e29a2e021a3fbfd440b7d159248b3eba5104e7b5efc402a909698ae46c971a",
"md5": "bcc9e347d1a69f1b34d1be80182f7ca2",
"sha256": "3f9633aeadeeeb9bb38269639355c2655bb093a47957a49f73be356644c5baf4"
},
"downloads": -1,
"filename": "usso-0.28.38.tar.gz",
"has_sig": false,
"md5_digest": "bcc9e347d1a69f1b34d1be80182f7ca2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19824,
"upload_time": "2025-07-27T16:06:36",
"upload_time_iso_8601": "2025-07-27T16:06:36.183324Z",
"url": "https://files.pythonhosted.org/packages/29/e2/9a2e021a3fbfd440b7d159248b3eba5104e7b5efc402a909698ae46c971a/usso-0.28.38.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 16:06:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ussoio",
"github_project": "usso-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "usso"
}
