From 1c9856300001a41b7d21b0a689e86014443ab64f Mon Sep 17 00:00:00 2001 From: Leo Vasanko Date: Fri, 19 Dec 2025 20:37:25 +0000 Subject: [PATCH] Docs updates. --- API.md | 12 ++---------- AuthFlow.md | 16 +++++++++++++--- Caddy.md | 5 ++--- 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/API.md b/API.md index 6c24894..e9881d0 100644 --- a/API.md +++ b/API.md @@ -1,16 +1,8 @@ # Paskia API -## Integrating with your app frontend +For integrating Paskia with your app frontend, see [AuthFlow](AuthFlow.md). -Protect API routes with forward-auth (see [Caddy](Caddy.md)). Optionally protect your app assets and not just the API. - -Catch response status 401/403 in fetch calls to protected endpoints and implement authentication flow in this case. The response is JSON and contains `auth.iframe` (a URL). [Render that URL in an iframe](AuthFlow.md) and retry the request after authentication. - -While the app is in (active) use, call `/auth/api/validate` occasionally to keep the session alive (session lifetime is 24h), otherwise the user will have to login every day. Max-age limits are unaffected by this and can be used on endpoints needing to reauthenticate with passkey more frequently. - -Use `/auth/api/user-info` to display user/session details, or link to `/auth/` if you prefer using the built-in profile UI and not having to anything more. - -### Web Interface +## Web Interface | Method | Path | What it is for | Notes | |---:|---|---|---| diff --git a/AuthFlow.md b/AuthFlow.md index 2ecccd7..ae299ec 100644 --- a/AuthFlow.md +++ b/AuthFlow.md @@ -1,6 +1,14 @@ -# API Authentication Flow (iframe) +# Integrating Paskia with your App -This document describes the frontend flow for handling `401/403` responses from endpoints protected by Paskia forward-auth, without ever exiting your app. +Protect API routes with forward-auth (see [Caddy](Caddy.md)). Optionally protect your app assets and not just the API. + +Catch response status 401/403 in fetch calls to protected endpoints and implement authentication flow in this case. The response is JSON and contains `detail` (an error message describing what is needed) and `auth.iframe` (a URL). Render that URL in an iframe and retry the request after authentication (see below). + +While the app is in (active) use, call `/auth/api/validate` occasionally to keep the session alive (session lifetime is 24h), otherwise the user will have to login every day. Max-age limits are unaffected by this and can be used on endpoints needing to reauthenticate with passkey more frequently. + +Fetch `/auth/api/user-info` to display user/session details, or link to `/auth/` if you prefer using the built-in profile UI and not having to do anything more. + +## Authentication Flow (iframe) ```js // Show an authentication dialog @@ -28,6 +36,8 @@ const handler = ev => { addEventListener('message', handler) ``` +This describes the frontend flow for handling 401/403 responses from endpoints protected by Paskia forward-auth, without ever exiting your app. + When a protected request fails, the backend returns 401 (needs auth / reauth) or 403 (missing permission). For API requests, the response is JSON that includes an iframe URL. Your app should render that URL in a full-screen iframe overlay, and retry the request after the iframe reports success. If it reports `auth-cancel`, don't try again. The backdrop for the dialog is a stylistic choice, and you can style the background shown with the dialog any way you wish, and consider using CSS file with the iframe rather than inline styles as used in the example. -If this seems too heavy for your needs, you can simply refresh the page or navigate to /auth/ but this will lose your app state and in the latter case affect navigation in a way that is not optimal. +Following this flow the user gets authenticated properly and after that your app keeps running as if nothing ever happened. diff --git a/Caddy.md b/Caddy.md index f8438c4..f75a25c 100644 --- a/Caddy.md +++ b/Caddy.md @@ -1,7 +1,6 @@ -# Paskia -## Caddy configuration +# Paskia Caddy configuration -We provide a few Caddy snippets that make the configuration easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the [auth folder](caddy/auth) with the snippets `require` and `setup` where your config file is (e.g. `/etc/caddy/auth`) +[Caddy](https://caddyserver.com/) is a modern web server that makes setting up web services easy. We provide a few Caddy snippets that make the configuration even easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the [auth folder](caddy/auth) with the snippets `require` and `setup` where your config file is (e.g. `/etc/caddy/auth`) What these snippets do - `setup`: Mount the auth UI at `/auth/` proxying to `:4401`