README
This commit is contained in:
Leo Vasanko
@@ -60,6 +60,104 @@ paskia [options]
|
||||
| --origin *url* | Restrict allowed origins for WebSocket auth (repeatable) | All under rp-id |
|
||||
| --auth-host *url* | Dedicated authentication site, e.g. **auth.example.com** | Use **/auth/** path on each site |
|
||||
|
||||
## Tutorial: From Local Testing to Production
|
||||
|
||||
This section walks you through a complete example, from running Paskia locally to protecting a real site in production.
|
||||
|
||||
### Step 1: Local Testing
|
||||
|
||||
For development and testing, run Paskia without any arguments:
|
||||
|
||||
```fish
|
||||
paskia
|
||||
```
|
||||
|
||||
This starts the server on [localhost:4401](http://localhost:4401) with passkeys bound to `localhost`. On first run, Paskia prints a registration link for the Master Admin—click it to register your first passkey.
|
||||
|
||||
### Step 2: Production Configuration
|
||||
|
||||
For a real deployment, configure Paskia with your domain name (rp-id). This enables SSO setup for that domain and any subdomains.
|
||||
|
||||
```fish
|
||||
paskia --rp-id example.com --rp-name "Example Corp"
|
||||
```
|
||||
|
||||
This binds passkeys to `*.example.com`. The `--rp-name` is shown to users during passkey registration.
|
||||
|
||||
### Step 3: Set Up Caddy
|
||||
|
||||
Install [Caddy](https://caddyserver.com/) and copy the [auth folder](caddy/auth) to `/etc/caddy/auth`. Say your current unprotected Caddyfile looks like this:
|
||||
|
||||
```caddyfile
|
||||
app.example.com {
|
||||
reverse_proxy :3000
|
||||
}
|
||||
```
|
||||
|
||||
Add Paskia full site protection:
|
||||
|
||||
```caddyfile
|
||||
app.example.com {
|
||||
import auth/setup
|
||||
handle {
|
||||
import auth/require perm=myapp:login
|
||||
reverse_proxy :3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Run `systemctl reload caddy`. Now `app.example.com` requires the `myapp:login` permission. Try accessing it and you'll land on a login dialog.
|
||||
|
||||
### Step 4: Assign Permissions via Admin Panel
|
||||
|
||||
1. Go to `app.example.com/auth/admin/`
|
||||
2. Create a permission, give it a name and scope `myapp:login`
|
||||
3. Assign it to Organization
|
||||
4. In that organization, assign it to the Administration role
|
||||
|
||||
Now you have granted yourself the new permission.
|
||||
|
||||
### Step 5: Add API Authentication to Your App
|
||||
|
||||
Your backend already receives `Remote-*` headers from Caddy's forward-auth. For frontend API calls, we provide a [JS paskia module](https://www.npmjs.com/package/paskia):
|
||||
|
||||
```js
|
||||
import { apiJson } from 'https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js'
|
||||
|
||||
const data = await apiJson('/api/sensitive', { method: 'POST' })
|
||||
```
|
||||
|
||||
When a 401/403 occurs, the auth dialog appears automatically, then the request retries.
|
||||
|
||||
To protect the API path with a different permission, update your Caddyfile:
|
||||
|
||||
```caddyfile
|
||||
app.example.com {
|
||||
import auth/setup
|
||||
|
||||
@api path /api/*
|
||||
handle @api {
|
||||
import auth/require perm=myapp:api
|
||||
reverse_proxy :3000
|
||||
}
|
||||
|
||||
handle {
|
||||
import auth/require perm=myapp:login
|
||||
reverse_proxy :3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create the `myapp:api` permission in the admin panel, that will be required for all API access. Link to `/auth/` for the built-in profile page.
|
||||
|
||||
You may also remove the `myapp:login` protection from the rest of your site paths, unless you wish to keep all your assets behind a login page. Having this as the last entry in your config allows free access to everything not matched by other sections.
|
||||
|
||||
```Caddyfile
|
||||
handle {
|
||||
reverse_proxy :3000
|
||||
}
|
||||
```
|
||||
|
||||
## Further Documentation
|
||||
|
||||
- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
|
||||
|
||||
+37
-106
@@ -8,26 +8,6 @@
|
||||
:root {
|
||||
color-scheme: light dark; /* Automatic themes by browser */
|
||||
}
|
||||
/* Login/reauth/forbidden dialog will appear in this iframe */
|
||||
#auth-iframe {
|
||||
/* Full viewport overlay */
|
||||
border: none;
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
z-index: 9999;
|
||||
/* Optional transparent background with optional blur backdrop */
|
||||
color-scheme: auto;
|
||||
background: transparent;
|
||||
backdrop-filter: blur(.1rem) brightness(0.7);
|
||||
-webkit-backdrop-filter: blur(.1rem) brightness(0.7);
|
||||
}
|
||||
/* Prevent background scroll when auth-iframe is shown */
|
||||
body:has(#auth-iframe) {
|
||||
overflow: hidden;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
@@ -65,99 +45,50 @@
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
<script type="module">
|
||||
import { apiFetch, apiJson, AuthCancelledError } from '/paskia-js/dist/paskia.js'
|
||||
|
||||
const output = document.getElementById('output');
|
||||
let pendingCall = null; // Stores the API call to retry after auth
|
||||
|
||||
// The auth iframe posts messages when authentication completes or is cancelled.
|
||||
// Message types: 'auth-success' (proceed), 'auth-back' (user cancelled)
|
||||
// Errors during auth stay in the dialog allowing retry, no message is sent.
|
||||
window.addEventListener('message', (event) => {
|
||||
const { type, message } = event.data || {};
|
||||
|
||||
if (type === 'auth-success') {
|
||||
log('✓ Authentication successful, retrying...');
|
||||
hideAuthIframe();
|
||||
// Retry the original API call that triggered authentication
|
||||
if (pendingCall) {
|
||||
const { url, method } = pendingCall;
|
||||
pendingCall = null;
|
||||
apiCall(url, method);
|
||||
}
|
||||
} else if (type === 'auth-back') {
|
||||
log(message || 'Authentication cancelled');
|
||||
hideAuthIframe();
|
||||
pendingCall = null;
|
||||
}
|
||||
});
|
||||
|
||||
// Make an API call, handling 401/403 by showing the auth iframe.
|
||||
// The server returns JSON with auth.iframe URL when authentication is needed.
|
||||
async function apiCall(url, method = 'GET') {
|
||||
log(`${method} ${url}...`);
|
||||
|
||||
const response = await fetch(url, { method });
|
||||
|
||||
// Server returns 401 (login/reauth) or 403 (missing permissions)
|
||||
// with a JSON body containing the iframe URL for authentication
|
||||
if (response.status === 401 || response.status === 403) {
|
||||
const data = await response.json();
|
||||
if (data.auth?.iframe) {
|
||||
const mode = data.auth.mode; // 'login' or 'reauth'
|
||||
log(`${mode === 'reauth' ? 'Re-authentication' : 'Authentication'} required...`);
|
||||
pendingCall = { url, method };
|
||||
showAuthIframe(data.auth.iframe);
|
||||
return;
|
||||
}
|
||||
log(`Error: ${response.status} - ${data.detail}`);
|
||||
return;
|
||||
}
|
||||
|
||||
// Forward endpoint returns 204 on success (Caddy then adds Remote-* headers)
|
||||
if (response.status === 204) {
|
||||
log('✓ Success (204 No Content)\nHeaders:\n' +
|
||||
[...response.headers].filter(([k]) => k.startsWith('remote-'))
|
||||
.map(([k, v]) => ` ${k}: ${v}`).join('\n'));
|
||||
return;
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
log(`Error: ${response.status} ${response.statusText}`);
|
||||
return;
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
log('✓ Response:\n' + JSON.stringify(data, null, 2));
|
||||
}
|
||||
|
||||
async function logout() {
|
||||
await fetch('/auth/api/logout', { method: 'POST' });
|
||||
log('Logged out');
|
||||
}
|
||||
|
||||
// Create fullscreen iframe for authentication.
|
||||
// The 'allow' attribute enables WebAuthn (passkey) API inside the iframe.
|
||||
function showAuthIframe(url) {
|
||||
hideAuthIframe();
|
||||
const iframe = document.createElement('iframe');
|
||||
iframe.id = 'auth-iframe';
|
||||
iframe.src = url;
|
||||
document.body.appendChild(iframe);
|
||||
log("Authentication dialog open...")
|
||||
}
|
||||
|
||||
function hideAuthIframe() {
|
||||
document.getElementById('auth-iframe')?.remove();
|
||||
}
|
||||
|
||||
function log(msg) {
|
||||
output.textContent = msg;
|
||||
}
|
||||
|
||||
// Make an API call using paskia module (handles 401/403 automatically)
|
||||
window.apiCall = async function(url, method = 'GET') {
|
||||
log(`${method} ${url}...`);
|
||||
try {
|
||||
const response = await apiFetch(url, { method });
|
||||
|
||||
// Forward endpoint returns 204 on success
|
||||
if (response.status === 204) {
|
||||
log('✓ Success (204 No Content)');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
log(`Error: ${response.status} ${response.statusText}`);
|
||||
return;
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
log('✓ Response:\n' + JSON.stringify(data, null, 2));
|
||||
} catch (e) {
|
||||
if (e instanceof AuthCancelledError) {
|
||||
log('Authentication cancelled');
|
||||
} else {
|
||||
log(`Error: ${e.message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
window.logout = async function() {
|
||||
await fetch('/auth/api/logout', { method: 'POST' });
|
||||
log('Logged out');
|
||||
}
|
||||
|
||||
// Browser mode: open the forward endpoint directly in a new window.
|
||||
// When Accept: text/html, the server redirects to the login page if needed,
|
||||
// then back to the original URL after authentication.
|
||||
function browserNav(url) {
|
||||
window.browserNav = function(url) {
|
||||
log('Opening in new window...\nIf not authenticated, you\'ll see the login page.\nAfter auth, you\'ll see a 204 response (blank page = success).');
|
||||
window.open(url, '_blank');
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user