magic-link-sso-django 1.3.0

magic-link-sso-django

Reusable Django integration package for the Magic Link SSO server.

Install

pip install magic-link-sso-django

Required settings

At minimum, configure:

MAGICSSO_SERVER_URL = 'http://localhost:3000'
MAGICSSO_JWT_SECRET = 'replace-me-with-a-long-random-jwt-secret'
MAGICSSO_PREVIEW_SECRET = 'replace-me-with-a-different-long-random-preview-secret'
MAGICSSO_COOKIE_NAME = 'magic-sso'

Other supported settings:

MAGICSSO_AUTH_EVERYWHERE = False
MAGICSSO_COOKIE_DOMAIN = None
MAGICSSO_COOKIE_MAX_AGE = None
MAGICSSO_COOKIE_PATH = '/'
MAGICSSO_COOKIE_SAMESITE = 'Lax'
MAGICSSO_COOKIE_SECURE = True
MAGICSSO_DIRECT_USE = False
MAGICSSO_PUBLIC_ORIGIN = 'https://app.example.com'
MAGICSSO_PUBLIC_URLS = ['login']
MAGICSSO_REQUEST_TIMEOUT = 5
MAGICSSO_TRUST_PROXY = False
MAGICSSO_ALLOWED_ORIGINS = ['https://app.example.com']

The package validates MAGICSSO_JWT_SECRET, MAGICSSO_PREVIEW_SECRET, MAGICSSO_SERVER_URL, MAGICSSO_COOKIE_NAME, MAGICSSO_COOKIE_SAMESITE, MAGICSSO_COOKIE_PATH, and the proxy/origin trust settings during app startup so configuration mistakes fail fast.

Auth tokens are site-bound. The middleware and built-in /sso/verify-email/ view verify the returned token against the current Django origin and the SSO server issuer. Upgrading to this release invalidates older session cookies that were issued without siteId/aud/iss, so users need to sign in again after deployment.

Keep USE_X_FORWARDED_HOST = False unless Django is only reachable through a trusted proxy that overwrites forwarded headers. If you do enable USE_X_FORWARDED_HOST, set MAGICSSO_TRUST_PROXY = True and configure either MAGICSSO_PUBLIC_ORIGIN or a strict MAGICSSO_ALLOWED_ORIGINS allowlist so site-bound JWT audience checks stay anchored to trusted origins.

Basic integration

1. Add 'magic_sso_django' to INSTALLED_APPS.
2. Add 'magic_sso_django.middleware.MagicSsoMiddleware' to MIDDLEWARE.
3. Include path('sso/', include('magic_sso_django.urls')) in urls.py.
4. Configure the required MAGICSSO_* settings.

Keep Django's CsrfViewMiddleware enabled and submit logout through a POST form with {% csrf_token %}. The built-in /sso/logout/ view is POST-only.

Verified requests expose both request.magic_sso_user_email and request.magic_sso_user_scope, and the decoded JWT payload now includes siteId for site-bound authorization checks. The built-in /sso/login/ view also accepts an optional scope query or form field and forwards it to the SSO server.

If the server enables [auth.otp], the packaged login form renders a single OTP field after sign-in. Its CSRF-protected /sso/verify-email/otp/ view exchanges the code server-side, validates the returned JWT, and sets the normal HTTP-only cookie.

Local development

uv sync --all-groups
uv run pytest