Add kaya-oidc package for OpenID Connect authentication

2026-07-18 04:56:07 +00:00
parent 079e6cce4b
commit 99e25bd8f1
15 changed files with 1013 additions and 3 deletions
@@ -0,0 +1,70 @@
+# kaya-oidc
+
+OpenID Connect authentication for the Kaya web framework.
+
+Built on top of `kaya-session` and implements the OIDC **Authorization Code
+Flow with PKCE**.
+
+## Usage
+
+```python
+import os
+from kaya.core import HttpContext, KayaApp
+from kaya.session import SessionMiddleware, InMemorySessionStore
+from kaya.oidc import OIDCConfig, OIDCApp
+
+app = KayaApp()
+session_app = SessionMiddleware(app, InMemorySessionStore())
+
+oidc = OIDCApp(
+    session_app,
+    OIDCConfig(
+        issuer=os.environ['OIDC_ISSUER'],
+        client_id=os.environ['OIDC_CLIENT_ID'],
+        client_secret=os.environ.get('OIDC_CLIENT_SECRET'),
+        redirect_uri='http://localhost:8000/auth/callback',
+        fetch_userinfo=True,
+    )
+)
+
+@oidc.GET('/')
+async def home(ctx: HttpContext):
+    await ctx.send_str(200, 'public home')
+
+@oidc.GET('/profile')
+@oidc.require_auth
+async def profile(ctx: HttpContext):
+    user = oidc.get_user(ctx)
+    await ctx.send_str(200, f'Hello {user.email or user.sub}')
+```
+
+## Features
+
+- Generic OIDC discovery
+- Authorization Code Flow with PKCE (S256)
+- ID token signature validation with JWKS
+- `state` and `nonce` protection
+- Session fixation defense via `regenerate_id()` after login
+- Optional userinfo endpoint fetch
+- Refresh token support
+- RP-initiated logout (when provider advertises `end_session_endpoint`)
+
+## Security notes
+
+- The `none` signing algorithm is rejected by default.
+- Only algorithms listed in `OIDCConfig.allowed_id_token_algorithms` are accepted.
+- Always use HTTPS for `redirect_uri` in production.
+
+## Supported flows
+
+Only the Authorization Code Flow with PKCE is supported. Implicit and Hybrid
+flows are intentionally not implemented.
+
+## Supported algorithms
+
+ID token signature verification supports:
+`RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`,
+`ES256`, `ES384`, `ES512`, and `EdDSA`.
+
+HMAC algorithms (`HS*`) are disabled by default and can be enabled by adding
+them to `allowed_id_token_algorithms` if your provider uses them.