weenspace-auth

WeenSpace Authentication.

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.
• Runtime mode selection for SP, IDP, or both.

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

poetry add weenspace-auth

or from local workspace:

poetry -C src/backend/weenspace-auth install

Integrate with a Django project

1. Add app to INSTALLED_APPS:

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

2. Use UUID-based custom user model:

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:

python manage.py migrate

4. OIDC endpoints exposed by this package:

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

Security behavior:

• next URLs are validated and restricted to same-host URLs.
• Invalid or external next values fall back to /.
• Token revocation endpoint accepts POST requests only.

5. Configure auth role mode (sp, idp, or both):

# Default is "sp"
WEENSPACE_AUTH_MODE = "sp"

# Optional explicit issuer for IDP discovery document.
WEENSPACE_AUTH_IDP_ISSUER = "https://auth.example.com/auth/oidc"

# Optional override for where IDP hooks are implemented.
WEENSPACE_AUTH_IDP_HOOKS_MODULE = "weenspace.auth"

# Keep this false in production. If true, IDP mode can run without required hooks.
WEENSPACE_AUTH_ALLOW_UNCONFIGURED_IDP = False

Mode behavior:

• sp: exposes provider login/callback/logout/revoke endpoints.
• idp: exposes IDP endpoints only.
• both: exposes both SP and IDP endpoint sets.
• Invalid WEENSPACE_AUTH_MODE values fail startup with a Django configuration error.
• In idp or both mode, startup fails unless all required IDP hooks are configured.

IDP endpoints:

/auth/oidc/.well-known/openid-configuration
/auth/oidc/authorize/
/auth/oidc/token/
/auth/oidc/userinfo/
/auth/oidc/jwks/

IDP request handling is hook-driven through optional functions in weenspace.auth:

• on_oidc_authorize_request(request)
• on_oidc_token_request(request)
• on_oidc_userinfo_request(request)
• on_oidc_jwks_request(request)

When hooks are not defined, IDP action endpoints return 501 Not Implemented.

6. Optional claim mapping and default assignment:

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",
    }
}

7. Optional provider config:

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",
    },
}

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

• docs/AUTH_USER_MODEL_MIGRATION_ROLLOUT.md
• docs/REPLACEMENT_READINESS_CHECKLIST.md
• docs/ZITADEL_COMPARISON.md

Publishing

This package is prepared for publishing to PyPI via Poetry:

poetry build
poetry publish

Local development with pyenv

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