Metadata-Version: 2.4
Name: exonware-xwauth
Version: 0.0.1.7
Summary: OAuth 2.0 / OIDC connector — AS core, tokens, sessions, federation (use exonware-xwlogin for IdPs & login)
Project-URL: Homepage, https://github.com/exonware/xwauth
Project-URL: Documentation, https://github.com/exonware/xwauth/docs
Project-URL: Repository, https://github.com/exonware/xwauth
Project-URL: Issues, https://github.com/exonware/xwauth/issues
Author-email: eXonware Backend Team <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: authentication,authorization,exonware,oauth2,oidc
Requires-Python: >=3.12
Requires-Dist: authlib>=1.2.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: exonware-xwaction
Requires-Dist: exonware-xwschema
Requires-Dist: exonware-xwsystem
Requires-Dist: fastapi>=0.104.0
Requires-Dist: oauthlib>=3.2.2
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: requests>=2.28.0
Requires-Dist: webauthn>=2.0.0
Provides-Extra: dev
Requires-Dist: exonware-xwaction; extra == 'dev'
Requires-Dist: exonware-xwaction[xw]; extra == 'dev'
Requires-Dist: exonware-xwdata; extra == 'dev'
Requires-Dist: exonware-xwdata[xw]; extra == 'dev'
Requires-Dist: exonware-xwentity; extra == 'dev'
Requires-Dist: exonware-xwentity[xw]; extra == 'dev'
Requires-Dist: exonware-xwjson; extra == 'dev'
Requires-Dist: exonware-xwjson[xw]; extra == 'dev'
Requires-Dist: exonware-xwlogin; extra == 'dev'
Requires-Dist: exonware-xwlogin[full]; extra == 'dev'
Requires-Dist: exonware-xwmodels; extra == 'dev'
Requires-Dist: exonware-xwmodels[xw]; extra == 'dev'
Requires-Dist: exonware-xwnode; extra == 'dev'
Requires-Dist: exonware-xwnode[xw]; extra == 'dev'
Requires-Dist: exonware-xwquery; extra == 'dev'
Requires-Dist: exonware-xwquery[xw]; extra == 'dev'
Requires-Dist: exonware-xwschema; extra == 'dev'
Requires-Dist: exonware-xwschema[xw]; extra == 'dev'
Requires-Dist: exonware-xwstorage; extra == 'dev'
Requires-Dist: exonware-xwstorage[xw]; extra == 'dev'
Requires-Dist: exonware-xwsystem[full]; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: lxml>=5.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: redis>=4.0.0; extra == 'dev'
Requires-Dist: signxml>=4.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: exonware-xwaction; extra == 'full'
Requires-Dist: exonware-xwaction[xw]; extra == 'full'
Requires-Dist: exonware-xwdata; extra == 'full'
Requires-Dist: exonware-xwdata[xw]; extra == 'full'
Requires-Dist: exonware-xwentity; extra == 'full'
Requires-Dist: exonware-xwentity[xw]; extra == 'full'
Requires-Dist: exonware-xwjson; extra == 'full'
Requires-Dist: exonware-xwjson[xw]; extra == 'full'
Requires-Dist: exonware-xwlogin; extra == 'full'
Requires-Dist: exonware-xwlogin[full]; extra == 'full'
Requires-Dist: exonware-xwmodels; extra == 'full'
Requires-Dist: exonware-xwmodels[xw]; extra == 'full'
Requires-Dist: exonware-xwnode; extra == 'full'
Requires-Dist: exonware-xwnode[xw]; extra == 'full'
Requires-Dist: exonware-xwquery; extra == 'full'
Requires-Dist: exonware-xwquery[xw]; extra == 'full'
Requires-Dist: exonware-xwschema; extra == 'full'
Requires-Dist: exonware-xwschema[xw]; extra == 'full'
Requires-Dist: exonware-xwstorage; extra == 'full'
Requires-Dist: exonware-xwstorage[xw]; extra == 'full'
Requires-Dist: exonware-xwsystem[full]; extra == 'full'
Requires-Dist: httpx>=0.27.0; extra == 'full'
Requires-Dist: lxml>=5.0.0; extra == 'full'
Requires-Dist: redis>=4.0.0; extra == 'full'
Requires-Dist: signxml>=4.0.0; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwaction; extra == 'lazy'
Requires-Dist: exonware-xwaction[xw]; extra == 'lazy'
Requires-Dist: exonware-xwdata; extra == 'lazy'
Requires-Dist: exonware-xwentity; extra == 'lazy'
Requires-Dist: exonware-xwjson; extra == 'lazy'
Requires-Dist: exonware-xwlazy; extra == 'lazy'
Requires-Dist: exonware-xwlogin; extra == 'lazy'
Requires-Dist: exonware-xwmodels; extra == 'lazy'
Requires-Dist: exonware-xwnode; extra == 'lazy'
Requires-Dist: exonware-xwquery; extra == 'lazy'
Requires-Dist: exonware-xwschema; extra == 'lazy'
Requires-Dist: exonware-xwschema[xw]; extra == 'lazy'
Requires-Dist: exonware-xwstorage; extra == 'lazy'
Requires-Dist: exonware-xwsystem[lazy]; extra == 'lazy'
Provides-Extra: xw
Requires-Dist: exonware-xwaction; extra == 'xw'
Requires-Dist: exonware-xwdata; extra == 'xw'
Requires-Dist: exonware-xwentity; extra == 'xw'
Requires-Dist: exonware-xwjson; extra == 'xw'
Requires-Dist: exonware-xwlogin; extra == 'xw'
Requires-Dist: exonware-xwmodels; extra == 'xw'
Requires-Dist: exonware-xwnode; extra == 'xw'
Requires-Dist: exonware-xwquery; extra == 'xw'
Requires-Dist: exonware-xwschema; extra == 'xw'
Requires-Dist: exonware-xwstorage; extra == 'xw'
Description-Content-Type: text/markdown

# xwauth

**OAuth 2.0 / OIDC connector** — authorization server primitives, tokens, sessions, federation core, and storage contracts. **Concrete IdPs, WebAuthn/MFA, OAuth RP clients, and FastAPI login route mixins** ship in sibling package **exonware-xwlogin** (`pip install exonware-xwauth[xwlogin]` pulls `exonware-xwlogin[handlers]`). Ties to xwentity, xwstorage, xwaction where you wire them. Docs in `docs/`; competitive notes in `.references/`.

**Target dependency direction (0.x migration):** *xwauth* **consumes** *xwlogin*; *xwlogin* must **not** depend on *xwauth* once foundation types move — see monorepo **[REF_41_DEPENDENCY_DIRECTIONS.md](../.docs/guides/REF_41_DEPENDENCY_DIRECTIONS.md)** (pip cannot cycle both ways until that move completes). **Attachment:** `exonware.xwauth.connectors.login_bridge` documents **in-process** (`load_login_package`) vs **remote** (**xwlogin-api** / HTTP) via `LoginRemoteConfig` (REF_41 §6). For HTTP clients: `pip install exonware-xwauth[login_remote]` (pulls **httpx**).

**Company:** eXonware.com · **Author:** eXonware Backend Team · **Email:** connect@exonware.com  

[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://exonware.com)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

## 📦 Install

```bash
pip install exonware-xwauth
pip install exonware-xwauth[lazy]
pip install exonware-xwauth[full]
pip install exonware-xwauth[xwlogin]   # exonware-xwlogin (IdPs, clients, FastAPI login mixins)
pip install exonware-xwauth[login_remote]   # httpx — HTTP client to xwlogin-api (REF_41 §6)
pip install exonware-xwauth[stack]   # xwjson, xwnode, xwdata, xwentity, xwmodels, xwquery — xwschema is core (REF_41 §8)
pip install "exonware-xwauth[enterprise]"   # SAML + storage + login handlers (self-hosted AS embedding)
```

After **`[stack]`**, optional: **`import exonware.xwauth.stack`** at process startup to eagerly import **xwjson** … **xwquery** (REF_41 §8).

SKUs and extras: [docs/REF_39_EDITION_AND_SKUS.md](docs/REF_39_EDITION_AND_SKUS.md).

Optional: `xwauth-server` for OAuth endpoints; see [docs/](docs/) when present.

---

## 🚀 Quick start

```python
from exonware.xwauth import *

# OAuth 2.0 flows, grant types, provider integration; entity-aware user/role persistence
# See docs/ and REF_* for full API and server setup
```

See [docs/](docs/) for usage, `REF_*`, and GUIDE_01_USAGE when present.

---

## ✨ What you get

| Area | What's in it |
|------|----------------|
| **Backend** | OAuth 2.0 / OpenID Connect; authorization code, client credentials, refresh; custom providers. |
| **Integration** | xwentity (user/role), xwstorage, xwaction. |
| **Server** | xwauth-server - OAuth endpoints, multi-tenant. |
| **Security** | Token encryption, sessions, CSRF, rate limiting. |

---

## 🌐 Exonware ecosystem advantage

XW-Auth is not only a standalone auth package. It is backed by the broader XW stack, so security, transport, storage, and API behavior stay consistent across services.
You can still use `xwauth` standalone with its core install and your existing stack.
Adopting more XW libraries is optional and primarily valuable when you need enterprise and mission-critical patterns with self-managed infrastructure control.

| XW library behind XW-Auth | Exact added value | Competitive edge vs typical auth stacks |
|------|----------------|----------------|
| **XWSystem** | Shared security contracts, principal normalization, OAuth error payload/status mapping, and codec/serialization plumbing. | You avoid framework-locked auth glue and inconsistent claim/error handling across services. |
| **XWStorage** | Pluggable auth persistence through one provider model (file/local today, extensible backends). | You can switch storage strategy without rewriting auth logic around a single ORM or IdP store. |
| **XWJSON** | Native structured serialization used with XWStorage-backed auth state. | Safer, more consistent state handling than ad-hoc JSON blobs spread across handlers. |
| **XWAction** | Declarative action/route integration for auth handlers and API endpoints. | Cleaner endpoint composition than scattering manual route wiring in each framework module. |
| **XWSchema** | Schema-level validation for security and authorization rule shapes. | Stronger policy correctness than relying only on runtime checks and hand-written guards. |
| **XWAPI** | Error-envelope parity between auth endpoints and the rest of your APIs. | Clients get one predictable failure contract instead of separate auth-vs-app error formats. |
| **XWEntity** | Domain-aligned user/role integration point for identity and authorization models. | Your auth layer matches your business entity model instead of living in an isolated user silo. |

This ecosystem alignment is the core differentiator: XW-Auth gives OAuth 2.0 features plus platform-level consistency from security primitives to storage and API contracts.

---

## 📖 Docs and tests

- **Security:** [docs/SECURITY.md](docs/SECURITY.md) (report vulnerabilities); [docs/SECURITY_ADVISORIES.md](docs/SECURITY_ADVISORIES.md) (advisory process); [docs/REF_26_INTEGRATOR_SECURITY_CHECKLIST.md](docs/REF_26_INTEGRATOR_SECURITY_CHECKLIST.md) (integrator checklist); MFA/WebAuthn: [docs/REF_MFA_WEBAUTHN_THREAT_MODEL.md](docs/REF_MFA_WEBAUTHN_THREAT_MODEL.md).
- **Competitive backlog:** [docs/REF_25_COMPETITIVE_ADVANCE_BACKLOG.md](docs/REF_25_COMPETITIVE_ADVANCE_BACKLOG.md) (20 extended ideas + TCO appendix).
- **Microbench (REF_25 #6):** `python -m exonware.xwauth.bench --iterations 2000` (after install or `PYTHONPATH=src`); see [benchmarks/README.md](benchmarks/README.md).
- **Score improvement roadmap:** [.references/ROADMAP_SCORE_20.md](.references/ROADMAP_SCORE_20.md) (20 competitive-rubric work items).
- **HA / upgrade runbook (starter):** [docs/GUIDE_03_HA_UPGRADE_RUNBOOK.md](docs/GUIDE_03_HA_UPGRADE_RUNBOOK.md) (ROADMAP #12).
- **Partner / edge matrix:** [docs/REF_33_PARTNER_INTEGRATION_MATRIX.md](docs/REF_33_PARTNER_INTEGRATION_MATRIX.md) (ROADMAP #19).
- **RFC / design process:** [docs/rfc/README.md](docs/rfc/README.md) (ROADMAP #18).
- **Multi-tenant reference story:** [docs/REF_37_MULTI_TENANT_REFERENCE_STACK.md](docs/REF_37_MULTI_TENANT_REFERENCE_STACK.md) (ROADMAP #13).
- **Observability (ROADMAP #14 — done):** [REF_63 landing](docs/REF_63_AUTH_OBSERVABILITY_CONTRACT.md); metrics/audit + **event catalog §8:** [REF_61](docs/REF_61_OPS_TELEMETRY_SCHEMA.md); SLI registry + **CI parity:** [REF_62](docs/REF_62_OPS_SLI_REGISTRY_V1.md) · `xwauth-api` workflow `core-tests` (`test_sli_registry_parity.py`).
- **Architecture diagrams:** [docs/GUIDE_04_REFERENCE_ARCHITECTURE_DIAGRAMS.md](docs/GUIDE_04_REFERENCE_ARCHITECTURE_DIAGRAMS.md) (ROADMAP #20).
- **Edition / pip SKUs:** [docs/REF_39_EDITION_AND_SKUS.md](docs/REF_39_EDITION_AND_SKUS.md) (ROADMAP #2).
- **Migration playbooks (ROADMAP #4):** [GUIDE_05 Keycloak](docs/GUIDE_05_MIGRATION_KEYCLOAK_SHAPED.md) · [GUIDE_06 Auth0](docs/GUIDE_06_MIGRATION_AUTH0_SHAPED.md) · [GUIDE_07 Supabase](docs/GUIDE_07_MIGRATION_SUPABASE_SHAPED.md); **client registry mapping:** [REF_64](docs/REF_64_CLIENT_REGISTRY_MIGRATION_MAPPING.md).
- **Reference SaaS outline (ROADMAP #3):** [GUIDE_08](docs/GUIDE_08_REFERENCE_SAAS_TEMPLATE_OUTLINE.md); **Terraform stub:** `xwauth-api/deploy/terraform/stub/`.
- **Thin OIDC client patterns (ROADMAP #16):** [GUIDE_09](docs/GUIDE_09_OIDC_THIN_CLIENT_PATTERNS.md) (PKCE, refresh §5).
- **Start:** [docs/INDEX.md](docs/INDEX.md) or [docs/](docs/).
- **Ops program:** [docs/REF_24_OPS_PERFECT_SCORE_EXECUTION_PLAN.md](docs/REF_24_OPS_PERFECT_SCORE_EXECUTION_PLAN.md) and `REF_60+` contracts.
- **Protocol rigor (ROADMAP #5):** [REF_53](docs/REF_53_PROTOCOL_TRACEABILITY_MATRIX.md), [REF_54](docs/REF_54_PROTOCOL_DEVIATION_REGISTER.md), [REF_55](docs/REF_55_PROTOCOL_PROFILE_SCHEMA_NOTES.md); **CI:** `xwauth-api` `.github/workflows/protocol-conformance.yml` (A/B/C); `xwauth` `.github/workflows/protocol-governance.yml` (deviation gate).
- **Federation / IdP quirks (Entra, Okta, Google):** [docs/REF_27_IDP_OIDC_QUIRKS.md](docs/REF_27_IDP_OIDC_QUIRKS.md), module `exonware.xwauth.federation.idp_quirks`.
- **SAML enterprise kit (ROADMAP #6):** [GUIDE_10](docs/GUIDE_10_SAML_ENTERPRISE_KIT.md) (`pip install "exonware-xwauth[saml]"` or `[enterprise]`).
- **SCIM hardening (ROADMAP #7):** [GUIDE_11](docs/GUIDE_11_SCIM_HARDENING.md) (`/v1/scim/v2/*`, pagination, errors, ETags).
- **Federation interop lab (ROADMAP #8):** [GUIDE_12](docs/GUIDE_12_FEDERATION_INTEROP_LAB.md); matrix: [docs/federation/INTEROP_MATRIX.md](docs/federation/INTEROP_MATRIX.md).
- **Email / magic-link ops (SPF/DKIM/DMARC):** [docs/REF_28_EMAIL_MAGIC_LINK_OPS.md](docs/REF_28_EMAIL_MAGIC_LINK_OPS.md), `exonware.xwauth.ops`.
- **Interop disclosure & fuzzing (draft):** [docs/REF_29_INTEROP_BOUNTY_AND_FUZZING.md](docs/REF_29_INTEROP_BOUNTY_AND_FUZZING.md), `exonware.xwauth.ops.research_program`.
- **Air-gapped / offline deploy:** [docs/REF_30_AIRGAP_DEPLOYMENT.md](docs/REF_30_AIRGAP_DEPLOYMENT.md), `exonware.xwauth.ops.airgap_deployment`.
- **Data residency:** [docs/REF_31_DATA_RESIDENCY.md](docs/REF_31_DATA_RESIDENCY.md), `exonware.xwauth.ops.data_residency`.
- **Multi-region AS:** [docs/REF_32_MULTI_REGION_AUTH.md](docs/REF_32_MULTI_REGION_AUTH.md), `exonware.xwauth.ops.multi_region_auth`.
- **Abuse resistance:** [docs/REF_33_ABUSE_RESISTANCE.md](docs/REF_33_ABUSE_RESISTANCE.md), `exonware.xwauth.ops.abuse_resistance`.
- **B2B delegated admin:** [docs/REF_34_B2B_DELEGATED_ADMIN.md](docs/REF_34_B2B_DELEGATED_ADMIN.md), `exonware.xwauth.ops.b2b_delegated_admin`.
- **Compliance pack (ROPA / DPA / subprocessors):** [docs/REF_35_COMPLIANCE_PACK.md](docs/REF_35_COMPLIANCE_PACK.md), `exonware.xwauth.ops.compliance_pack`.
- **Login UI accessibility (WCAG-oriented checklist):** [docs/REF_36_LOGIN_UI_ACCESSIBILITY.md](docs/REF_36_LOGIN_UI_ACCESSIBILITY.md), `exonware.xwauth.ops.login_ui_accessibility`.
- **TCO benchmark evidence:** [docs/REF_37_TCO_BENCHMARK_EVIDENCE.md](docs/REF_37_TCO_BENCHMARK_EVIDENCE.md), `exonware.xwauth.ops.tco_evidence` (`validate_microbench_output`, publish checklist).
- **Pen test engagement (executive summary path):** [docs/REF_38_PENETRATION_TEST_ENGAGEMENT.md](docs/REF_38_PENETRATION_TEST_ENGAGEMENT.md), `exonware.xwauth.ops.pen_test_engagement`.
- **OIDC self-cert readiness:** [docs/REF_39_OIDC_SELF_CERT_READINESS.md](docs/REF_39_OIDC_SELF_CERT_READINESS.md), `exonware.xwauth.ops.oidc_self_cert_readiness`.
- **IaC (Terraform/Pulumi) for tenants & clients:** [docs/REF_40_INFRA_AS_CODE_TENANTS.md](docs/REF_40_INFRA_AS_CODE_TENANTS.md), `exonware.xwauth.ops.infra_as_code_tenants`.
- **Kubernetes operator readiness:** [docs/REF_41_KUBERNETES_OPERATOR_READINESS.md](docs/REF_41_KUBERNETES_OPERATOR_READINESS.md), `exonware.xwauth.ops.kubernetes_operator_readiness`.
- **Admin API + OpenAPI parity:** [docs/REF_42_ADMIN_API_OPENAPI_PARITY.md](docs/REF_42_ADMIN_API_OPENAPI_PARITY.md), `exonware.xwauth.ops.admin_api_openapi_parity`.
- **Extension model readiness:** [docs/REF_43_EXTENSION_MODEL_READINESS.md](docs/REF_43_EXTENSION_MODEL_READINESS.md), `exonware.xwauth.ops.extension_model_readiness`.
- **Session / device reference UI:** [docs/REF_44_SESSION_DEVICE_REFERENCE_UI.md](docs/REF_44_SESSION_DEVICE_REFERENCE_UI.md), `exonware.xwauth.ops.session_device_reference_ui`; HTTP mixins: `exonware.xwauth.handlers.mixins.sessions` (`GET /auth/sessions` JSON + Bearer revoke; `GET /auth/sessions/view` HTML — Bearer or documented cookie `xwauth_reference_access_token`).
- **Tests:** From repo root, follow the project's test layout.

---

## 📜 License and links

Apache-2.0 - see [LICENSE](LICENSE). **Homepage:** https://exonware.com · **Repository:** https://github.com/exonware/xwauth  


## ⏱️ Async Support

<!-- async-support:start -->
- xwauth includes asynchronous execution paths in production code.
- Source validation: 560 async def definitions and 643 await usages under src/.
- Use async APIs for I/O-heavy or concurrent workloads to improve throughput and responsiveness.
<!-- async-support:end -->
Version: 0.0.1.7 | Updated: 11-Apr-2026

*Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025*
