updated auth
This commit is contained in:
Gamosoft
parent
2738d64c26
commit
c9a73a4a1b
|
|
@ -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.
|
||||
Restart the app to apply.
|
||||
|
|
|
|||
Loading…
Reference in New Issue