LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Implement stateful OIDC as Session objects. Add refresh tokens and backchannel logout.

Browse Source
This commit is contained in:
Leo Vasanko
2026-02-15 03:48:10 +00:00
parent 8132189a04
commit 18722f0e01
10 changed files with 609 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
oidc.md
+117 -25
View File
@@ -1,7 +1,7 @@
# OIDC Provider Implementation
## Overview
Minimal OpenID Connect 1.0 provider implementation for Paskia, enabling third-party apps to authenticate users via passkeys.
OpenID Connect 1.0 provider implementation for Paskia, enabling third-party apps to authenticate users via passkeys. Features stateful sessions with refresh tokens and back-channel logout support.
## Database Changes
@@ -9,6 +9,23 @@ Minimal OpenID Connect 1.0 provider implementation for Paskia, enabling third-pa
- `email: str | None` — omit if None
- `preferred_username: str` — initially derived from full name, require unique and non-empty
### Session model additions (in `db/structs.py`)
Sessions now support both native (cookie-based) and OIDC authentication:
```python
class Session(msgspec.Struct, dict=True, omit_defaults=True):
user_uuid: UUID
credential_uuid: UUID # Always captured (passkey used for auth)
host: str
ip: str
user_agent: str
expiry: datetime
client_uuid: UUID | None = None # If set, this is an OIDC session
```
- Native sessions: `client_uuid` is None, validated via `session_ctx()`
- OIDC sessions: `client_uuid` set, looked up via `oidc_session_by_sid()`
- Session key serves as both cookie token (native) and `sid` claim (OIDC)
### New OIDC-specific models
```python
class OIDClient(msgspec.Struct):
@@ -19,27 +36,29 @@ class OIDClient(msgspec.Struct):
created_at: datetime
def verify_secret(self, secret: str) -> bool: ...
```
class OIDAuthCode(msgspec.Struct):
code: str # dict key, secure random
client: UUID
user: UUID
### In-memory auth codes (`paskia/oidauth.py`)
Authorization codes are stored in-memory only (not persisted), with 60-second lifetime:
```python
@dataclass
class AuthCode:
code: str
client_uuid: UUID
user_uuid: UUID
redirect_uri: str
scope: str
sid: str # Session ID for backchannel logout
nonce: str | None
code_challenge: str | None # PKCE
code_challenge: str | None
code_challenge_method: str | None
created_at: datetime
expires_at: datetime # 10 minutes
@classmethod
def create(cls, ...) -> OIDAuthCode: ...
expires_at: datetime # 60 seconds
```
### DB additions
```python
oid_clients: dict[UUID, OIDClient] = {}
oid_auth_codes: dict[str, OIDAuthCode] = {}
```
## Endpoints
@@ -49,8 +68,9 @@ oid_auth_codes: dict[str, OIDAuthCode] = {}
- `GET /.well-known/jwks.json` — Public keys for token verification
### OIDC routes (`/auth/oidc/`)
- `POST /auth/oidc/token` — Token endpoint (code exchange)
- `POST /auth/oidc/token` — Token endpoint (code exchange & refresh)
- `GET /auth/oidc/userinfo` — UserInfo endpoint (bearer token)
- `POST /auth/oidc/backchannel-logout` — Back-channel logout endpoint
### Authorization (via existing restricted app)
- `GET /auth/restricted/oidc?client_id=...&redirect_uri=...&response_type=code&scope=openid...`
@@ -74,6 +94,7 @@ The restricted app detects OIDC params from URL and handles authentication via W
```json
{
"sub": "user-uuid",
"sid": "session-id",
"name": "Alice",
"preferred_username": "alice",
"email": "alice@example.com",
@@ -83,24 +104,92 @@ The restricted app detects OIDC params from URL and handles authentication via W
## Authorization Flow
The `/auth/restricted/oidc` page handles OIDC authorization (same code as `/auth/restricted/iframe` for API auth):
The `/auth/restricted/oidc` page handles OIDC authorization:
1. Client redirects to `/auth/restricted/oidc?client_id=...&redirect_uri=...&response_type=code&scope=openid&state=...`
2. Frontend detects OIDC params from `window.location.search`
3. Frontend passes raw query string to `/auth/ws/authenticate?{query_string}`
4. User authenticates via passkey
5. WebSocket validates client/redirect_uri, authenticates user, creates auth code
6. WebSocket returns `{"redirect_url": "redirect_uri?code=...&state=..."}`
7. Frontend redirects to the URL
8. Client exchanges code at `/auth/oidc/token` → receives `id_token` + `access_token`
9. Optionally calls `/auth/oidc/userinfo` with bearer token
5. WebSocket validates client/redirect_uri, authenticates user
6. **Creates OIDC session** (persisted, with credential/IP/user_agent)
7. Creates auth code with session's `sid`
8. WebSocket returns `{"redirect_url": "redirect_uri?code=...&state=..."}`
9. Frontend redirects to the URL
10. Client exchanges code at `/auth/oidc/token` → receives tokens
**Token Response:**
```json
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "{sid}",
"id_token": "..."
}
```
**Key design points:**
- No session created during OIDC auth (stateless for the OIDC client)
- OIDC sessions are persisted (credential, IP, user_agent recorded)
- Session key becomes `sid` claim and `refresh_token`
- Raw query string preserved throughout (no parsing/reconstruction of redirect_uri)
- Redirect URI validated against client's registered URIs via exact string match
- PKCE required (S256 only)
## Refresh Tokens
The `refresh_token` returned is the OIDC session's `sid`. On refresh:
**Request:**
```
POST /auth/oidc/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={sid}&client_id=...&client_secret=...
```
**Behavior:**
1. Validates session exists and belongs to client
2. Checks session not expired
3. Extends session expiry to +24h (sliding window, matching native sessions)
4. Records current IP and user_agent
5. Issues new `access_token` and `id_token` (with same `sid`)
6. Returns same `refresh_token` (the sid is stable)
**Session lifetime:** 24 hours with sliding window via refresh — same as native sessions.
## Back-Channel Logout
Supports OIDC Back-Channel Logout 1.0.
**Discovery claims:**
```json
{
"backchannel_logout_supported": true,
"backchannel_logout_session_supported": true
}
```
**Endpoint:** `POST /auth/oidc/backchannel-logout`
**Request:**
```
POST /auth/oidc/backchannel-logout
Content-Type: application/x-www-form-urlencoded
logout_token={jwt}
```
The `logout_token` JWT must contain:
- `sid` — specific session to terminate, OR
- `sub` — terminate all sessions for user (optionally filtered by `aud` client)
**Behavior:**
1. Decode and verify logout token signature
2. Look up session(s) by `sid` or `sub`
3. Verify client (`aud`) matches session's `client_uuid`
4. Delete session(s)
5. Return 200 OK (even if no sessions found, per spec)
## WebSocket OIDC Mode
The `/auth/ws/authenticate` WebSocket accepts optional OIDC query params:
@@ -112,21 +201,25 @@ The `/auth/ws/authenticate` WebSocket accepts optional OIDC query params:
When OIDC params present:
- Validates client and redirect_uri before authentication
- Creates auth code after successful passkey auth
- Performs passkey authentication
- Creates OIDC session via `db.oidc_login()` (persists credential, IP, user_agent)
- Creates auth code with session's sid
- Returns `{"redirect_url": "..."}` instead of session token
When OIDC params absent:
- Normal authentication flow with session creation
- Normal authentication flow with native session creation
## Files
### Created
- `paskia/db/structs.py` — Added `OIDClient`, `OIDAuthCode` models; User fields `email`, `preferred_username`
- `paskia/db/operations.py` — CRUD for OIDC entities
- `paskia/fastapi/oid.py` — Token and userinfo endpoints
- `paskia/oidauth.py` — In-memory auth code storage (60-second lifetime, no persistence)
- `paskia/db/structs.py` — Added `OIDClient` model; Session `client_uuid` field; User fields `email`, `preferred_username`
- `paskia/db/operations.py` — CRUD for OIDC clients; `oidc_login()` function
- `paskia/fastapi/oid.py` — Token, userinfo, and backchannel-logout endpoints
- `paskia/util/oidjwt.py` — Ed25519 key management, JWT creation, JWKS
### Modified
- `paskia/globals.py` — Initialize oidauth on startup
- `paskia/fastapi/mainapp.py` — Mount OIDC app, well-known endpoints
- `paskia/fastapi/ws.py` — OIDC params support in `/authenticate`
- `frontend/src/utils/passkey.js` — Pass query string to authenticate
@@ -137,4 +230,3 @@ When OIDC params absent:
- Master admin UI for client management
- User UI for editing preferred_username, email, profile picture
- Token revocation endpoint (optional)
- Logout/session management spec (optional)