/authentication

Authentication & OAuth2

> Add OAuth2 authentication to PyWry apps — Google, GitHub, Microsoft, or any OIDC provider.

Two Modes

Native Mode (Desktop)

Opens a dedicated auth window → user logs in at provider → callback captured on ephemeral localhost server → tokens returned.

from pywry import PyWry

app = PyWry()
result = app.login()  # Blocks until auth completes

if result.success:
    app.show("<h1>Welcome!</h1>")
    app.block()

Deploy Mode (Production)

Auth routes mounted automatically when `auth_enabled=True` and `oauth2` settings are configured.

PYWRY_DEPLOY__AUTH_ENABLED=true
PYWRY_OAUTH2__PROVIDER=google
PYWRY_OAUTH2__CLIENT_ID=your-id
PYWRY_OAUTH2__CLIENT_SECRET=your-secret

Routes: `GET /auth/login`, `GET /auth/callback`, `POST /auth/refresh`, `POST /auth/logout`, `GET /auth/status`, `GET /auth/userinfo`

Configuration

Environment Variables

# Provider: google, github, microsoft, oidc, custom
PYWRY_OAUTH2__PROVIDER=google

# Credentials
PYWRY_OAUTH2__CLIENT_ID=your-client-id
PYWRY_OAUTH2__CLIENT_SECRET=your-client-secret

# Scopes (space-separated)
PYWRY_OAUTH2__SCOPES=openid email profile

# PKCE (recommended for public clients)
PYWRY_OAUTH2__USE_PKCE=true

# Token storage: memory (default), keyring (native), redis (deploy)
PYWRY_OAUTH2__TOKEN_STORE_BACKEND=memory

# Custom provider endpoints
PYWRY_OAUTH2__AUTHORIZE_URL=https://provider.com/authorize
PYWRY_OAUTH2__TOKEN_URL=https://provider.com/token

# OIDC auto-discovery
PYWRY_OAUTH2__ISSUER_URL=https://accounts.google.com

TOML Configuration

[tool.pywry.oauth2]
provider = "github"
client_id = "your-id"
scopes = "read:user user:email"
use_pkce = true
token_store_backend = "memory"

Provider Setup

Google

from pywry.auth import GoogleProvider
provider = GoogleProvider(client_id="...", client_secret="...")
result = app.login(provider=provider)

GitHub

from pywry.auth import GitHubProvider
provider = GitHubProvider(client_id="...", client_secret="...")
result = app.login(provider=provider)

Microsoft (Azure AD)

from pywry.auth import MicrosoftProvider
provider = MicrosoftProvider(client_id="...", tenant_id="your-tenant")
result = app.login(provider=provider)

Custom OIDC

from pywry.auth import GenericOIDCProvider
provider = GenericOIDCProvider(
    client_id="...",
    issuer_url="https://your-idp.com",  # Auto-discovers endpoints
)
result = app.login(provider=provider)

Frontend Auth State

When authenticated, `window.__PYWRY_AUTH__` is set with `{ user_id, roles, token_type }`.

// Check auth
window.pywry.auth.isAuthenticated()

// Get state
window.pywry.auth.getState()  // { authenticated, user_id, roles, token_type }

// React to changes
window.pywry.auth.onAuthStateChange((state) => {
    console.log('Auth changed:', state);
});

Token Storage Backends

| Backend | Use Case | Persistence | |---------|----------|-------------| | `memory` | Development, single-process | None (lost on restart) | | `keyring` | Native desktop apps | OS credential manager | | `redis` | Deploy mode, multi-worker | Redis with TTL |

Install keyring support: `pip install pywry[auth]`

Security Notes

• PKCE is enabled by default (public client best practice)
• CSRF protection via `state` parameter validation
• Tokens are never injected into HTML — passed via secure cookies or IPC
• Session cookies are `HttpOnly`, `Secure`, `SameSite=Lax`
• Background token refresh happens automatically before expiry