builderadmin
/
NoteDiscovery
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

updated auth

This commit is contained in:
Gamosoft 2026-01-12 12:22:24 +01:00
parent 2738d64c26
commit c9a73a4a1b
1 changed files with 80 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
documentation/AUTHENTICATION.md
View File

@ -1,83 +1,68 @@
# 🔒 NoteDiscovery Authentication Guide # 🔒 NoteDiscovery Authentication Guide
## ⚠️ **IMPORTANT: Default Password Warning** ## ⚠️ Default Password Warning
> **The default `config.yaml` includes authentication disabled by default, with password: `admin`** > **Default password is `admin`** — CHANGE THIS before exposing to any network!
>
> 🔴 **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.
--- ---
## Overview ## 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 / self-hosted use
- ✅ Passwords hashed with bcrypt
- ✅ **Single User** - Perfect for personal/self-hosted use - ✅ Session-based (7 days default, configurable)
- ✅ **Secure** - Passwords hashed with bcrypt
- ✅ **Session-based** - Stay logged in for 7 days (configurable)
--- ---
## 🚀 Quick Setup ## Quick Test (Local Only)
**Default Configuration:** For local testing, authentication is **disabled by default**. To test with auth:
- Authentication is **disabled by default**
- Default password is `admin`
- Default secret key is insecure
**⚠️ IMPORTANT:** For production or network-exposed deployments, **change both the password and secret key immediately**. 1. Set `authentication.enabled: true` in `config.yaml`
2. Restart the app
---
### 🧪 **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`
3. Log in with password: `admin` 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: 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 ```bash
# Docker run # Docker
docker run -e AUTHENTICATION_ENABLED=true \ docker exec -it notediscovery python -c "import secrets; print(secrets.token_hex(32))"
-e AUTHENTICATION_PASSWORD=your_secure_password \
...
# Docker Compose (.env file) # Local
AUTHENTICATION_ENABLED=true python -c "import secrets; print(secrets.token_hex(32))"
AUTHENTICATION_PASSWORD=your_secure_password ```
**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:** **Via config.yaml:**
@ -85,142 +70,96 @@ AUTHENTICATION_PASSWORD=your_secure_password
authentication: authentication:
enabled: true enabled: true
password: "your_secure_password" 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: For users who prefer to hash passwords themselves.
#### Step 1: Generate a Password Hash
**Docker Users:**
**Generate a hash:**
```bash ```bash
# Docker Compose with the GHCR compose file # Docker
docker-compose -f docker-compose.ghcr.yml exec notediscovery python generate_password.py
# Or with docker run
docker exec -it notediscovery python generate_password.py docker exec -it notediscovery python generate_password.py
```
**Local Users:** # Local
```bash
# Install bcrypt if not already installed
pip install bcrypt
# Run the password generator
python generate_password.py python generate_password.py
``` ```
The script will: **Then configure:**
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:
```yaml ```yaml
authentication: authentication:
# Enable authentication
enabled: true enabled: true
password_hash: "$2b$12$..." # paste your hash here
# Session secret key (paste the output from Step 2) secret_key: "your_generated_secret_key"
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
``` ```
--- ---
### Restart the Application ### Step 3: Restart & Test
```bash ```bash
# If running locally # Docker Compose
uvicorn backend.main:app --reload
# If using Docker Compose
docker-compose restart docker-compose restart
# Or with docker run # Docker run
docker restart notediscovery docker restart notediscovery
# Local
python run.py
``` ```
### Test Login Navigate to `http://localhost:8000` — you'll be redirected to the login page.
Navigate to `http://localhost:8000` and you'll be redirected to the login page.
Enter the password you configured.
--- ---
## 🔒 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 ### ✅ What This Protects
- Unauthorized access to your notes - Unauthorized access to your notes
- Viewing, creating, editing, and deleting notes
- All API endpoints - All API endpoints
- Viewing, creating, editing, deleting notes
### ⚠️ What This Doesn't Protect ### ⚠️ 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 - ❌ Multi-user environments
- ❌ Public internet exposure without HTTPS - ❌ Public internet without HTTPS
- ❌ Production SaaS applications
- ❌ Compliance requirements (HIPAA, GDPR, etc.) - ❌ Compliance requirements (HIPAA, GDPR, etc.)
### 🛡️ Best Practices ### 🛡️ Best Practices
1. **Use HTTPS** - Always run behind a reverse proxy (Traefik, nginx, Caddy) with SSL/TLS 1. **Use HTTPS** — Run behind a reverse proxy (Traefik, nginx, Caddy)
2. **Strong Password** - Use at least 12 characters with mixed case, numbers, and symbols 2. **Strong password** — At least 12 characters, mixed case, numbers, symbols
3. **Unique Secret Key** - Never reuse secret keys across applications 3. **Unique secret key** — Never reuse across applications
4. **Keep Config Secure** - Don't commit `config.yaml` with real credentials to version control 4. **Keep config secure** — Don't commit credentials to version control
5. **VPN/Private Network** - Keep NoteDiscovery on a private network or behind a VPN
--- ---
## 🚫 Disabling Authentication ## Disabling Authentication
To disable authentication and allow open access:
```yaml ```yaml
authentication: authentication:
enabled: false enabled: false
``` ```
Restart the application, and authentication will be bypassed. Restart the app to apply.