NoteDiscovery/documentation/AUTHENTICATION.md

🔒 NoteDiscovery Authentication Guide

⚠️ Default Password Warning

Default password is admin — CHANGE THIS before exposing to any network!

---

Overview

NoteDiscovery includes simple password protection for single-user deployments. When enabled, users must log in before accessing notes.

• ✅ Single user / self-hosted use
• ✅ Passwords hashed with bcrypt
• ✅ Session-based (7 days default, configurable)

---

Quick Test (Local Only)

For local testing, authentication is disabled by default. To test with auth:

1. Set authentication.enabled: true in config.yaml
2. Restart the app
3. Log in with password: admin

⚠️ Don't use the default password on any network!

---

Production Setup

For any deployment exposed to a network, follow these steps:

Step 1: Generate a Secret Key

The secret key encrypts session cookies. Generate a random one:

# Docker
docker exec -it notediscovery python -c "import secrets; print(secrets.token_hex(32))"

# Local
python -c "import secrets; print(secrets.token_hex(32))"

Save this key — you'll need it in Step 2.

---

Step 2: Configure Authentication

Your password is automatically hashed at startup using bcrypt.

Via Environment Variables (Docker):

docker run -d \
  -e AUTHENTICATION_ENABLED=true \
  -e AUTHENTICATION_PASSWORD=your_secure_password \
  -e AUTHENTICATION_SECRET_KEY=your_generated_secret_key \
  ...

Via config.yaml:

authentication:
  enabled: true
  password: "your_secure_password"
  secret_key: "your_generated_secret_key"

---

Step 3: Restart & Test

# Docker Compose
docker-compose restart

# Docker run
docker restart notediscovery

# Local
python run.py

Navigate to http://localhost:8000 — you'll be redirected to the login page.

---

Configuration Priority

Environment variables override config.yaml:

Priority	Source
1st	AUTHENTICATION_PASSWORD env var
2nd	password in config.yaml

Example: If you set AUTHENTICATION_PASSWORD as an env var, it overrides config.yaml.

---

Security Considerations

✅ What This Protects

• Unauthorized access to your notes
• All API endpoints
• Viewing, creating, editing, deleting notes

⚠️ What This Doesn't Protect

This is a simple single-user system. NOT suitable for:

• ❌ Multi-user environments
• ❌ Public internet without HTTPS
• ❌ Compliance requirements (HIPAA, GDPR, etc.)

🛡️ Best Practices

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

---

API Key Authentication

For external integrations (MCP servers, scripts, automation), use an API key instead of session cookies.

Setup

# Generate a secure key
python -c "import secrets; print(secrets.token_hex(32))"

Via Environment Variable:

docker run -e AUTHENTICATION_API_KEY=your_api_key ...

Via config.yaml:

authentication:
  api_key: "your_64_character_hex_key"

Usage

# Option 1: Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/api/notes

# Option 2: X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/api/notes

Both session auth (web UI) and API key auth work simultaneously when enabled.

---

Disabling Authentication

authentication:
  enabled: false

Restart the app to apply.