Skip to main content

​
Dashboard Authentication

Protect your CCS dashboard with optional username/password authentication. Disabled by default for backward compatibility.
Authentication is completely optional. If not configured, the dashboard remains accessible without login (default behavior).

​
Quick Setup

​
Step 1: Generate Password Hash

Use bcrypt to hash your password: 
npx bcrypt-cli hash 'your-secure-password'
This outputs a hash like: $2b$10$...

​
Step 2: Configure Authentication

Add to ~/.ccs/config.yaml:
dashboard_auth:
  enabled: true
  username: admin
  password_hash: "$2b$10$your-bcrypt-hash-here"
  session_timeout_hours: 24  # Optional, default: 24

​
Step 3: Restart Dashboard

ccs config
The dashboard will now require login.

​
Login Flow

When authentication is enabled:
  1. Navigate to dashboard URL (http://localhost:3000)
  2. You’re redirected to login page
  3. Enter username and password
  4. On success, redirected to original destination
  5. Session persists for configured timeout (default: 24 hours)

​
Logout

Click the user menu in the dashboard header and select Sign Out.

​
Configuration Reference

KeyTypeDefaultDescription
enabledbooleanfalseEnable/disable authentication
usernamestring""Login username
password_hashstring""Bcrypt-hashed password
session_timeout_hoursnumber24Session duration in hours

​
Environment Variables

VariableMaps To
CCS_DASHBOARD_AUTH_ENABLEDdashboard_auth.enabled
CCS_DASHBOARD_USERNAMEdashboard_auth.username
CCS_DASHBOARD_PASSWORD_HASHdashboard_auth.password_hash
CCS_SESSION_SECRETCustom session encryption key
Environment variables take priority over config.yaml values.

​
Security Features

Session-Based Auth

Uses httpOnly cookies (not localStorage) to prevent XSS attacks

Rate Limiting

5 login attempts per 15 minutes per IP address

Bcrypt Hashing

Industry-standard password hashing (10 rounds)

Persistent Secret

Session secret persisted across restarts

​
Best Practices

Never commit your password hash to version control. Use environment variables for sensitive deployments.
  1. Use strong passwords: At least 12 characters with mixed case, numbers, and symbols
  2. Rotate passwords: Change passwords periodically
  3. Secure transport: Use HTTPS if exposing dashboard externally (via reverse proxy)
  4. Single user: This feature supports one user; for multi-user, use external auth proxy

​
Troubleshooting

​
”Too many login attempts”

Rate limiting triggered. Wait 15 minutes or restart the dashboard.

​
Session expires unexpectedly

Increase session_timeout_hours in config or check if ~/.ccs/.session-secret file exists.

​
Login not working after restart

Ensure password hash is correctly formatted in YAML (wrap in quotes if it contains special characters).