Metadata-Version: 2.4
Name: weenspace-auth
Version: 0.1.2
Summary: WeenSpace Identity Service Provider library for Django
License: MIT
Keywords: django,auth,oidc,identity,weenspace
Author: WeenSpace
Author-email: dev@weenspace.com
Requires-Python: >=3.14,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Dist: authlib (>=1.6,<2)
Requires-Dist: django (>=6.1,<6.2)
Requires-Dist: requests (>=2.32,<3)
Description-Content-Type: text/markdown

# weenspace-auth

Identity Service Provider library for WeenSpace projects.

## What this package provides

- Django app extending the auth stack with UUID v4 identities.
- User, organization, and account models for multi-account and multi-organization structure.
- External identity bindings for Microsoft, Google, Apple, Zitadel, and custom OIDC-compatible providers.
- Bridge hooks to leverage logic from the existing `weenspace.auth` module when present.

## Data model overview

- A user can belong to many organizations.
- A user can belong to many accounts.
- An organization can own many accounts.
- No tenant concepts are modeled in this package.

## Requirements

- Python 3.14+
- Django 6.1+

## Install

```bash
poetry add weenspace-auth
```

or from local workspace:

```bash
poetry -C src/backend/weenspace-auth install
```

## Integrate with a Django project

1. Add app to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "weenspace.auth",
]
```

2. Use UUID-based custom user model:

```python
AUTH_USER_MODEL = "weenspace_auth.IdentityUser"
```

Note:
- Django requires `AUTH_USER_MODEL` to use `app_label.ModelName`.
- Keep the app label `weenspace_auth` in `AUTH_USER_MODEL` for compatibility.
- Values like `weenspace.auth.IdentityUser` are not valid in Django settings.

3. Run migrations:

```bash
python manage.py migrate
```

4. OIDC endpoints exposed by this package:

```text
/auth/oidc/<provider>/login/
/auth/oidc/<provider>/callback/
/auth/oidc/logout/
/auth/oidc/<provider>/logout/
/auth/oidc/<provider>/revoke/
```

5. Optional claim mapping and default assignment:

```python
WEENSPACE_AUTH_DEFAULT_ORGANIZATION_SLUG = "default-org"
WEENSPACE_AUTH_DEFAULT_ACCOUNT_SLUG = "default-account"

WEENSPACE_AUTH_PROVIDERS = {
    "google": {
        "client_id": "...",
        "client_secret": "...",
        "issuer": "https://accounts.google.com",
        "organization_claim": "org_slug",
        "account_claim": "account_slug",
        "auto_create_org_account": True,
        "end_session_endpoint": "",
        "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
        "revocation_auth_method": "client_secret_post",
    }
}
```

    6. Optional provider config:

```python
WEENSPACE_AUTH_PROVIDERS = {
    "microsoft": {
        "client_id": "...",
        "client_secret": "...",
        "issuer": "https://login.microsoftonline.com/common/v2.0",
        "scopes": ["openid", "email", "profile"],
        "end_session_endpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/logout",
    },
    "google": {
        "client_id": "...",
        "client_secret": "...",
        "issuer": "https://accounts.google.com",
        "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
    },
    "apple": {
        "client_id": "...",
        "client_secret": "...",
        "issuer": "https://appleid.apple.com",
        "revocation_endpoint": "https://appleid.apple.com/auth/revoke",
    },
    "zitadel": {
        "client_id": "...",
        "client_secret": "...",
        "issuer": "https://<your-zitadel-domain>",
        "end_session_endpoint": "https://<your-zitadel-domain>/oidc/v1/end_session",
        "revocation_endpoint": "https://<your-zitadel-domain>/oauth/v2/revoke",
    },
}
```

7. For production migration planning when switching the user model, follow:

- `docs/AUTH_USER_MODEL_MIGRATION_ROLLOUT.md`

## Publishing

This package is prepared for publishing to PyPI via Poetry:

```bash
poetry build
poetry publish
```

## Local development with pyenv

```bash
pyenv install -s 3.14.0
pyenv local 3.14.0
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install poetry
poetry install
poetry run pytest
```

