Docs updates.
This commit is contained in:
Leo Vasanko
+64
@@ -0,0 +1,64 @@
|
||||
# Paskia API
|
||||
|
||||
For integrating Paskia with your app frontend, see [integration](Integration.md).
|
||||
|
||||
## Web Interface
|
||||
|
||||
| Method | Path | What it is for | Notes |
|
||||
|---:|---|---|---|
|
||||
| GET | `/auth/` | User profile page | |
|
||||
| GET | `/auth/admin/` | Admin panel | Requires auth:admin (master) or org admin permissions. |
|
||||
| GET | `/auth/{token}` | Reset / add credential URL (QR code link) | E.g. `/auth/fun.cotton.fresh.xray.lava` |
|
||||
|
||||
### Public JSON API: `/auth/api/*`
|
||||
|
||||
| Method | Path | Used for | Notes |
|
||||
|---:|---|---|---|
|
||||
| GET | `/auth/api/settings` | Paskia configuration | Returns RP info + base paths + session cookie name |
|
||||
| POST | `/auth/api/user-info` | Full user profile | Basic information, credentials, sessions, permissions |
|
||||
| POST | `/auth/api/logout` | Terminate session and delete session cookie | Signs out of the current site |
|
||||
| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable), `max_age=` |
|
||||
| GET | `/auth/api/forward` | Validate access (Caddy/Nginx) | 204 on success; 401/403 otherwise (HTML if requested) |
|
||||
|
||||
The `validate` and `forward` endpoints take query arguments `perm=` and `max_age=` for specific requirements on the validation of the current session.
|
||||
|
||||
### User JSON API: `/auth/api/user/*`
|
||||
|
||||
| Method | Path | Used for | Notes |
|
||||
|---:|---|---|---|
|
||||
| PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
|
||||
| POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie |
|
||||
| DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued |
|
||||
| DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication |
|
||||
| POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication |
|
||||
|
||||
These are used mostly from the user profile panel and modify the current user.
|
||||
|
||||
### Admin API: `/auth/api/admin/*`
|
||||
|
||||
Normally only used via admin panel, requires auth admin permissions and can modify any users, orgs and permissions the session has access to.
|
||||
|
||||
E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin `auth:admin` can see everything and create and manage orgs.
|
||||
|
||||
### WebSockets: `/auth/ws/*`
|
||||
|
||||
| Path | Used for | Notes |
|
||||
|---|---|---|
|
||||
| `WS /auth/ws/authenticate` | Passkey authentication | Returns a session token |
|
||||
| `WS /auth/ws/register` | Register a new credential | Adding another passkey to current user or via reset token |
|
||||
| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Used from unauthenticated client |
|
||||
| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used to accept the request, if same words are entered |
|
||||
|
||||
These are for internal use only, but are documented here because they are the core piece in all passkey operations.
|
||||
|
||||
### Auth host mode (`--auth-host`)
|
||||
|
||||
#### On the auth host:
|
||||
- The Web UI is served at site root (e.g. admin UI at `/admin/`), and the `/auth/...` equivalents (e.g. `/auth/admin/`) redirect to the root paths.
|
||||
- All of the API stays under `/auth/api/*`
|
||||
- Auth WebSockets remain at `/auth/ws/*` but take connections from other hosts to issue sessions for each of those.
|
||||
|
||||
#### On non-auth hosts:
|
||||
- `/auth/` shows only minimal profile and allows logging out of the current site
|
||||
- `/auth/api/*` is served normally.
|
||||
- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Paskia Caddy Configuration
|
||||
|
||||
[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`
|
||||
- `require`: Use `/auth/api/forward` for access control
|
||||
- Render a login page or a permission denied page if needed (without changing URL)
|
||||
|
||||
Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [trusted headers](Headers.md) for details.
|
||||
|
||||
We assume the normal unprotected **Caddyfile** for your site looks like this:
|
||||
|
||||
```caddyfile
|
||||
app.example.com {
|
||||
@public path /.well-known/* /favicon.ico
|
||||
handle @public {
|
||||
root * /var/www/
|
||||
file_server
|
||||
}
|
||||
|
||||
handle {
|
||||
reverse_proxy :3000 # Your app backend
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: We use the `handle @name` approach rather than `handle_path` to keep the path unaltered. Unlike bare directives, these blocks will be tried in sequence and each can contain what you'd typically put in your site definition (by default `reverse_proxy` takes precedence and nothing reaches the static files).
|
||||
|
||||
We will adapt from this to protect your app.
|
||||
|
||||
### Protect your site (auth/setup, auth/require)
|
||||
|
||||
```caddyfile
|
||||
app.example.com {
|
||||
import auth/setup
|
||||
|
||||
@public path /.well-known/* /favicon.ico
|
||||
handle @public {
|
||||
root * /var/www/
|
||||
file_server
|
||||
}
|
||||
|
||||
@reports path /reports
|
||||
handle @reports {
|
||||
import auth/require perm=myapp:reports
|
||||
reverse_proxy :3000
|
||||
}
|
||||
|
||||
handle {
|
||||
import auth/require max-age=12h
|
||||
reverse_proxy :3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The above setup allows unauthenticated access to certain files, then implements two different access controls for your backend app depending on which path is accessed. Note that the perm and max-age options may be combined, e.g. ``perm=myapp:admin&max-age=5min` on a very sensitive endpoint. This will require additional authentication if the passkey hasn't been used in the last 5 minutes (automatic session renewals don't affect this). Use `""` if you only want the user to be authenticated with no time or perm requirements.
|
||||
|
||||
### Dedicated Authentication Site
|
||||
|
||||
When you setup a separate subdomain for the authentication site, just add to your config another section for the auth host:
|
||||
|
||||
```
|
||||
auth.example.com {
|
||||
reverse_proxy :4401
|
||||
}
|
||||
```
|
||||
|
||||
Remember to specify `paskia serve --auth-host auth.example.com` to restrict the authentication services to this domain.
|
||||
|
||||
Note that we still reserve `/auth/` on each site for logout page and any APIs your application may require, while full user profile and global options are only available on the auth host.
|
||||
|
||||
Paskia does not require CORS configuration, but it can access the authentication and registration of auth host WS API from the other sites as WebSockets don't require any CORS.
|
||||
|
||||
### Override the paskia backend address (AUTH_UPSTREAM)
|
||||
|
||||
By default, the auth service is contacted at localhost port 4401. You can point Caddy to a different address by setting the `AUTH_UPSTREAM` environment variable for Caddy.
|
||||
|
||||
If unset, the snippets use `:4401` by default.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Paskia Trusted Headers for Apps
|
||||
|
||||
| HTTP Header | Meaning | Example |
|
||||
|---|---|---|
|
||||
| `Remote-User` | Authenticated user UUID | **01c03276-b8f0-**… (string) |
|
||||
| `Remote-Name` | User display name | **John Doe** |
|
||||
| `Remote-Org` | Organization UUID | Identifier for user's org (string) |
|
||||
| `Remote-Org-Name` | Organization display name | **The Company Ltd.** |
|
||||
| `Remote-Role` | Role UUID | Identifier for user's role (string) |
|
||||
| `Remote-Role-Name` | Role display name | **Employee** |
|
||||
| `Remote-Groups` | Permissions the user has, comma separated | **auth:admin,yourapp:reports** |
|
||||
| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601 UTC) | **2030-12-31T23:59:59Z** |
|
||||
| `Remote-Credential` | Credential UUID | Identifier for the sign-in passkey (string) |
|
||||
|
||||
Similar headers are also used by other authentication systems like [Authelia](https://www.authelia.com/integration/trusted-header-sso/introduction/) to signal the backend application information about the signed in user.
|
||||
|
||||
When a request is allowed, the auth service adds these headers by the forward-auth mechanism before proxying to your app as **request headers**. Your app can use them for user context to show on UI, or for its own authentication needs (e.g. prevent different orgs messing up with each other's data, logging which user performed an action).
|
||||
|
||||
Only the UUID values should be used for identification needs, because they never change, even when things are renamed (display names change), and are never reused (created on authentication server). They are UUIDv7 so you can also extract the creation timestamp from them.
|
||||
|
||||
Any `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md) to avoid dealing with any fake headers.
|
||||
|
||||
Note: the headers are intended primarily for the backend, while either frontend or backend (passing the session cookie) can request `/auth/api/user-info` for more complete information, and that is the recommended way to do it in the frontend. See [integration](Integration.md) for more.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Integrating Paskia with your App
|
||||
|
||||
Protect API routes with forward-auth (see [Caddy configuration](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
|
||||
const iframe = document.createElement('iframe')
|
||||
iframe.src = auth.url // from 401/403 response JSON
|
||||
iframe.style.cssText = `
|
||||
position: fixed;
|
||||
inset: 0;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
border: 0;
|
||||
z-index: 9999;
|
||||
background: transparent;
|
||||
backdrop-filter: blur(0.1rem) brightness(0.7);
|
||||
`
|
||||
document.body.appendChild(iframe)
|
||||
|
||||
// Wait until user is finished with the dialog
|
||||
const handler = ev => {
|
||||
if (ev.origin !== location.origin) return
|
||||
iframe.remove()
|
||||
removeEventListener('message', handler)
|
||||
if (ev.data?.type === 'auth-success') retry_original_fetch()
|
||||
}
|
||||
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.
|
||||
|
||||
Following this flow the user gets authenticated properly and after that your app keeps running as if nothing ever happened.
|
||||
Reference in New Issue
Block a user