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).
Enable dashboard auth whenever the bind is reachable from another device, including when you run ccs config --host 0.0.0.0.

​
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. If you plan to expose the dashboard beyond localhost, configure auth before switching to a non-loopback bind.

​
Login Flow

When authentication is enabled:
  1. Navigate to the dashboard URL printed by ccs config for the current session
  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).