Updated documentation.
This commit is contained in:
@@ -1,128 +1,61 @@
|
|||||||
# Paskia
|
# Paskia
|
||||||
|
|
||||||
A minimal FastAPI WebAuthn server with WebSocket support for passkey registration. This project demonstrates WebAuthn registration flow with Resident Keys (discoverable credentials) using modern Python tooling.
|
An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
|
||||||
|
|
||||||
## Features
|
## What is Paskia?
|
||||||
|
|
||||||
- 🔐 WebAuthn registration with Resident Keys support
|
- Easy to use fully featured auth&auth system (login and permissions)
|
||||||
- 🔌 WebSocket-based communication for real-time interaction
|
- Organization and role-based access control (optional)
|
||||||
- 🚀 Modern Python packaging with `pyproject.toml`
|
* Org admins control their users and roles
|
||||||
- 🎨 Clean, responsive HTML interface using @simplewebauthn/browser
|
* Master admin can create multiple independent orgs
|
||||||
- 📦 No database required - challenges stored locally per connection
|
* Master admin makes permissions available for orgs to assign
|
||||||
- 🛠️ Development tools: `ruff` for linting and formatting
|
- User Profile and Administration by API and web interface.
|
||||||
- 🧹 Clean architecture with local challenge management
|
under `/auth/` or `auth.example.com`
|
||||||
|
- Reset tokens and additional device linking via QR code or codewords.
|
||||||
|
- Pure Python, FastAPI, packaged with prebuilt Vue frontend
|
||||||
|
|
||||||
## Docs
|
Two interfaces:
|
||||||
|
- API fetch: auth checks and login without leaving your app
|
||||||
|
- Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx)
|
||||||
|
|
||||||
- Caddy integration: see `CADDY.md` for short, copy-paste snippets to secure your site with Caddy.
|
The API mode is useful for applications that can be customized to run with Paskia. Forward auth can also protect your javascript and other assets. Each provides fine-grained permission control and reauthentication requests where needed, and both can be mixed where needed.
|
||||||
|
|
||||||
## Requirements
|
Single Sign-On (SSO): Users register once and authenticate across all applications under your domain name (configured rp-id).
|
||||||
|
|
||||||
- Python 3.9+
|
|
||||||
- A WebAuthn-compatible authenticator (security key, biometric device, etc.)
|
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Install (editable dev mode)
|
Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
|
||||||
|
|
||||||
```fish
|
```fish
|
||||||
uv pip install -e .[dev]
|
uvx paskia serve --rp-id example.com
|
||||||
```
|
```
|
||||||
|
|
||||||
### Run (new CLI)
|
On the first run it downloads the software and prints a registration link for the Admin. Consider `uv tool install paskia` for a permanent install of `paskia` CLI.
|
||||||
|
|
||||||
`paskia` now provides subcommands:
|
The server will start up on [localhost:4401](http://localhost:4401) "for authentication required", serving for `*.example.com`.
|
||||||
|
|
||||||
|
If you are going to be connecting `localhost` directly, for testing, leave out the rp-id. Otherwise you will need a web server such as [Caddy](https://caddyserver.com/) to serve HTTPS on your actual domain names and proxy requests to Paskia and your backend apps.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
There is no config file. Pass only the options on CLI:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
paskia serve [host:port] [--options]
|
paskia serve [options]
|
||||||
```
|
```
|
||||||
|
|
||||||
Examples (fish shell shown):
|
Options (all optional):
|
||||||
|
|
||||||
```fish
|
- Listen address (one of):
|
||||||
# Production style (no reload)
|
* `[host]:port`: Address and port (default: `localhost:4401`)
|
||||||
paskia serve
|
* `unix:/path.sock`: Unix socket
|
||||||
paskia serve 0.0.0.0:8080 --rp-id example.com --origin https://example.com
|
- `--rp-id <domain>`: Domain name for authentication (required for production)
|
||||||
|
- `--rp-name "<text>"`: Name of your company or site (default: same as rp-id)
|
||||||
|
- `--origin <url>`: Explicit single site (default: `https://<rp-id>`)
|
||||||
|
- `--auth-host <domain>`: Dedicated authentication site (e.g., `auth.example.com`)
|
||||||
|
|
||||||
# Development (auto-reload via scripts/dev.py)
|
## Documentation
|
||||||
python scripts/dev.py # localhost:4401
|
|
||||||
python scripts/dev.py :5500 # localhost on port 5500
|
|
||||||
python scripts/dev.py 127.0.0.1 # host only, default port 4401
|
|
||||||
```
|
|
||||||
|
|
||||||
Available options (both subcommands):
|
- `API.md`: Complete HTTP and WebSocket API reference
|
||||||
|
- `Caddy.md`: Caddy configuration examples
|
||||||
```text
|
- `Headers.md`: HTTP headers passed to protected applications
|
||||||
--rp-id <id> Relying Party ID (default: localhost)
|
|
||||||
--rp-name <name> Relying Party name (default: same as rp-id)
|
|
||||||
--origin <url> Explicit origin (default: https://<rp-id>)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Legacy Invocation
|
|
||||||
|
|
||||||
If you previously used `python -m paskia.fastapi --dev --host ...`, switch to the new form above. The old flags `--host`, `--port`, and `--dev` are replaced by using `scripts/dev.py` for development mode.
|
|
||||||
|
|
||||||
## Usage (Web)
|
|
||||||
|
|
||||||
1. Start the server with one of the commands above
|
|
||||||
2. Open your browser to `http://localhost:4401/auth/` (or your chosen host/port)
|
|
||||||
3. Enter a username (or use the default)
|
|
||||||
4. Click "Register Passkey"
|
|
||||||
5. Follow your authenticator's prompts
|
|
||||||
|
|
||||||
Real-time status updates stream over WebSocket.
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
### Code Quality
|
|
||||||
|
|
||||||
```fish
|
|
||||||
# Run linting and formatting with ruff
|
|
||||||
uv run ruff check .
|
|
||||||
uv run ruff format .
|
|
||||||
|
|
||||||
# Or with hatch
|
|
||||||
hatch run ruff check .
|
|
||||||
hatch run ruff format .
|
|
||||||
```
|
|
||||||
|
|
||||||
### Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
paskia/
|
|
||||||
├── paskia/
|
|
||||||
│ ├── __init__.py
|
|
||||||
│ └── main.py # FastAPI server with WebSocket support
|
|
||||||
├── static/
|
|
||||||
│ └── index.html # Frontend interface
|
|
||||||
├── pyproject.toml # Modern Python packaging configuration
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
## Technical Details
|
|
||||||
|
|
||||||
### WebAuthn Configuration
|
|
||||||
|
|
||||||
- **Relying Party ID**: `localhost` (for development)
|
|
||||||
- **Resident Keys**: Required (enables discoverable credentials)
|
|
||||||
- **User Verification**: Preferred
|
|
||||||
- **Supported Algorithms**: ECDSA-SHA256, RSASSA-PKCS1-v1_5-SHA256
|
|
||||||
|
|
||||||
### WebSocket Message Flow
|
|
||||||
|
|
||||||
1. Client connects to `/ws/{client_id}`
|
|
||||||
2. Client sends `registration_challenge` message
|
|
||||||
3. Server responds with `registration_challenge_response`
|
|
||||||
4. Client completes WebAuthn ceremony and sends `registration_response`
|
|
||||||
5. Server verifies and responds with `registration_success` or `error`
|
|
||||||
|
|
||||||
### Security Notes
|
|
||||||
|
|
||||||
- This is a minimal demo - challenges are stored locally per WebSocket connection
|
|
||||||
- For production use, implement proper user storage and session management
|
|
||||||
- Consider using Redis or similar for challenge storage in production with multiple server instances
|
|
||||||
- Ensure HTTPS in production environments
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT License - feel free to use this as a starting point for your own WebAuthn implementations!
|
|
||||||
|
|||||||
+2
-2
@@ -33,8 +33,8 @@
|
|||||||
<body>
|
<body>
|
||||||
<div class="container">
|
<div class="container">
|
||||||
<header>
|
<header>
|
||||||
<h1>🔐 Paskia</h1>
|
<h1>🔐 Paskia - Development Server</h1>
|
||||||
<p class="subtitle">Development server demonstration page.</p>
|
<p class="subtitle">The following features are available after you have registered your Admin account and logged in. You should also use the Admin Site to create non-privileged users to see the Forbidden dialog caused by missing permissions.</p>
|
||||||
</header>
|
</header>
|
||||||
|
|
||||||
<div class="content">
|
<div class="content">
|
||||||
|
|||||||
+2
-1
@@ -5,7 +5,8 @@ build-backend = "hatchling.build"
|
|||||||
[project]
|
[project]
|
||||||
name = "paskia"
|
name = "paskia"
|
||||||
dynamic = ["version"]
|
dynamic = ["version"]
|
||||||
description = "Passkey Authentication for Web Services"
|
description = "Passkey Auth made easy: all sites and APIs can be guarded even without any changes on the protected site."
|
||||||
|
keywords = [ "forward_auth", "auth_request", "FastAPI" ]
|
||||||
authors = [
|
authors = [
|
||||||
{name = "Leo Vasanko"},
|
{name = "Leo Vasanko"},
|
||||||
]
|
]
|
||||||
|
|||||||
Reference in New Issue
Block a user