From c9a73a4a1bc97d83e61a96a55b8374bd46b43857 Mon Sep 17 00:00:00 2001 From: Gamosoft Date: Mon, 12 Jan 2026 12:22:24 +0100 Subject: [PATCH] updated auth --- documentation/AUTHENTICATION.md | 221 ++++++++++++-------------------- 1 file changed, 80 insertions(+), 141 deletions(-) diff --git a/documentation/AUTHENTICATION.md b/documentation/AUTHENTICATION.md index ed53822..7d5c6b7 100644 --- a/documentation/AUTHENTICATION.md +++ b/documentation/AUTHENTICATION.md @@ -1,83 +1,68 @@ # ๐Ÿ”’ NoteDiscovery Authentication Guide -## โš ๏ธ **IMPORTANT: Default Password Warning** +## โš ๏ธ Default Password Warning -> **The default `config.yaml` includes authentication disabled by default, with password: `admin`** -> -> ๐Ÿ”ด **CHANGE THIS if you're exposing NoteDiscovery to a network!** -> -> The default configuration is provided for **quick testing only**. Follow the setup guide below to set your own secure password and secret key. +> **Default password is `admin`** โ€” CHANGE THIS before exposing to any network! --- ## Overview -NoteDiscovery includes a simple, secure authentication system for single-user deployments. When enabled, users must log in with a password before accessing the application. +NoteDiscovery includes simple password protection for single-user deployments. When enabled, users must log in before accessing notes. -## โœจ Features - -- โœ… **Single User** - Perfect for personal/self-hosted use -- โœ… **Secure** - Passwords hashed with bcrypt -- โœ… **Session-based** - Stay logged in for 7 days (configurable) +- โœ… Single user / self-hosted use +- โœ… Passwords hashed with bcrypt +- โœ… Session-based (7 days default, configurable) --- -## ๐Ÿš€ Quick Setup +## Quick Test (Local Only) -**Default Configuration:** -- Authentication is **disabled by default** -- Default password is `admin` -- Default secret key is insecure +For local testing, authentication is **disabled by default**. To test with auth: -**โš ๏ธ IMPORTANT:** For production or network-exposed deployments, **change both the password and secret key immediately**. - ---- - -### ๐Ÿงช **Quick Test (Use Default Password)** - -For **local testing only**, you can use the default configuration: - -1. Start NoteDiscovery (Docker or locally) -2. Navigate to `http://localhost:8000` +1. Set `authentication.enabled: true` in `config.yaml` +2. Restart the app 3. Log in with password: `admin` -**โš ๏ธ Only use this for local testing on your own machine!** +โš ๏ธ **Don't use the default password on any network!** --- -### ๐Ÿ”’ **Production Setup (Change Password & Secret Key)** +## Production Setup For any deployment exposed to a network, follow these steps: ---- +### Step 1: Generate a Secret Key -## Password Configuration Options +The secret key encrypts session cookies. Generate a random one: -NoteDiscovery supports two ways to set passwords: - -| Method | Best For | Security | -|--------|----------|----------| -| **Plain text password** | Docker, PikaPods, easy deployment | Password is hashed at startup | -| **Pre-hashed password** | Advanced users, extra security | You control the hashing | - -Both methods are secure - the plain text option simply hashes the password when the app starts. - ---- - -### Option A: Plain Text Password (Recommended for Docker/PikaPods) - -The easiest approach - just set your password directly: - -**Via Environment Variable:** ```bash -# Docker run -docker run -e AUTHENTICATION_ENABLED=true \ - -e AUTHENTICATION_PASSWORD=your_secure_password \ - ... +# Docker +docker exec -it notediscovery python -c "import secrets; print(secrets.token_hex(32))" -# Docker Compose (.env file) -AUTHENTICATION_ENABLED=true -AUTHENTICATION_PASSWORD=your_secure_password +# Local +python -c "import secrets; print(secrets.token_hex(32))" +``` + +**Save this key** โ€” you'll need it in Step 2. + +--- + +### Step 2: Configure Authentication + +Choose **one** of these options: + +#### Option A: Plain Text Password (Recommended) + +The easiest approach. Your password is automatically hashed at startup. + +**Via Environment Variables (Docker):** +```bash +docker run -d \ + -e AUTHENTICATION_ENABLED=true \ + -e AUTHENTICATION_PASSWORD=your_secure_password \ + -e AUTHENTICATION_SECRET_KEY=your_generated_secret_key \ + ... ``` **Via config.yaml:** @@ -85,142 +70,96 @@ AUTHENTICATION_PASSWORD=your_secure_password authentication: enabled: true password: "your_secure_password" - secret_key: "your_generated_secret_key_here" + secret_key: "your_generated_secret_key" ``` -The password is automatically hashed with bcrypt when the app starts. - --- -### Option B: Pre-Hashed Password (Advanced) +#### Option B: Pre-Hashed Password (Advanced) -For users who prefer to hash passwords themselves: - -#### Step 1: Generate a Password Hash - -**Docker Users:** +For users who prefer to hash passwords themselves. +**Generate a hash:** ```bash -# Docker Compose with the GHCR compose file -docker-compose -f docker-compose.ghcr.yml exec notediscovery python generate_password.py - -# Or with docker run +# Docker docker exec -it notediscovery python generate_password.py -``` -**Local Users:** - -```bash -# Install bcrypt if not already installed -pip install bcrypt - -# Run the password generator +# Local python generate_password.py ``` -The script will: -1. Prompt you for your password (input is hidden) -2. Ask you to confirm it -3. Generate a bcrypt hash -4. Display the hash with instructions - -**Copy the hash** - you'll need it for Step 3. - -#### Step 2: Generate a Secret Key - -Generate a random secret key for session encryption: - -**Docker Users:** -```bash -docker-compose exec notediscovery python -c "import secrets; print(secrets.token_hex(32))" - -# Or with docker run -docker exec -it notediscovery python -c "import secrets; print(secrets.token_hex(32))" -``` - -**Local Users:** -```bash -python -c "import secrets; print(secrets.token_hex(32))" -``` - -**Copy the key** - you'll need it for Step 3. - -#### Step 3: Update `config.yaml` - -Edit your `config.yaml` and update the authentication section: - +**Then configure:** ```yaml authentication: - # Enable authentication enabled: true - - # Session secret key (paste the output from Step 2) - secret_key: "your_generated_secret_key_here" - - # Password hash (paste the output from Step 1) - password_hash: "$2b$12$..." - - # Session expiry in seconds (7 days by default) - session_max_age: 604800 + password_hash: "$2b$12$..." # paste your hash here + secret_key: "your_generated_secret_key" ``` --- -### Restart the Application +### Step 3: Restart & Test ```bash -# If running locally -uvicorn backend.main:app --reload - -# If using Docker Compose +# Docker Compose docker-compose restart -# Or with docker run +# Docker run docker restart notediscovery + +# Local +python run.py ``` -### Test Login - -Navigate to `http://localhost:8000` and you'll be redirected to the login page. - -Enter the password you configured. +Navigate to `http://localhost:8000` โ€” you'll be redirected to the login page. --- -## ๐Ÿ”’ Security Considerations +## Configuration Priority + +If multiple sources are configured, this priority applies (first wins): + +| Priority | Source | Type | +|----------|--------|------| +| 1st | `AUTHENTICATION_PASSWORD` env var | Plain text | +| 2nd | `AUTHENTICATION_PASSWORD_HASH` env var | Pre-hashed | +| 3rd | `password` in config.yaml | Plain text | +| 4th | `password_hash` in config.yaml | Pre-hashed | + +**Example:** If you set `AUTHENTICATION_PASSWORD` as an env var, it overrides anything in config.yaml. + +--- + +## Security Considerations ### โœ… What This Protects - Unauthorized access to your notes -- Viewing, creating, editing, and deleting notes - All API endpoints +- Viewing, creating, editing, deleting notes ### โš ๏ธ What This Doesn't Protect -This is a **simple authentication system** designed for **self-hosted, single-user** deployments. It is **NOT** suitable for: +This is a **simple single-user** system. NOT suitable for: - โŒ Multi-user environments -- โŒ Public internet exposure without HTTPS -- โŒ Production SaaS applications +- โŒ Public internet without HTTPS - โŒ Compliance requirements (HIPAA, GDPR, etc.) ### ๐Ÿ›ก๏ธ Best Practices -1. **Use HTTPS** - Always run behind a reverse proxy (Traefik, nginx, Caddy) with SSL/TLS -2. **Strong Password** - Use at least 12 characters with mixed case, numbers, and symbols -3. **Unique Secret Key** - Never reuse secret keys across applications -4. **Keep Config Secure** - Don't commit `config.yaml` with real credentials to version control -5. **VPN/Private Network** - Keep NoteDiscovery on a private network or behind a VPN +1. **Use HTTPS** โ€” Run behind a reverse proxy (Traefik, nginx, Caddy) +2. **Strong password** โ€” At least 12 characters, mixed case, numbers, symbols +3. **Unique secret key** โ€” Never reuse across applications +4. **Keep config secure** โ€” Don't commit credentials to version control --- -## ๐Ÿšซ Disabling Authentication - -To disable authentication and allow open access: +## Disabling Authentication ```yaml authentication: enabled: false ``` -Restart the application, and authentication will be bypassed. \ No newline at end of file +Restart the app to apply.