|
| 1 | +# HomelabARR Authentication System |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +HomelabARR includes a comprehensive authentication system to secure your container management interface. The system uses JWT tokens for stateless authentication and bcrypt for secure password hashing. |
| 6 | + |
| 7 | +## Features |
| 8 | + |
| 9 | +### 🔐 Security Features |
| 10 | +- **JWT-based authentication** - Stateless, secure token-based auth |
| 11 | +- **Bcrypt password hashing** - Industry-standard password security |
| 12 | +- **Role-based access control** - Admin and user roles |
| 13 | +- **Automatic token validation** - Expired tokens are handled gracefully |
| 14 | +- **Secure session management** - Automatic logout on token expiration |
| 15 | + |
| 16 | +### 👤 User Management |
| 17 | +- **Default admin account** - Created automatically on first run |
| 18 | +- **Password management** - Users can change their own passwords |
| 19 | +- **User profiles** - Username, email, role, last login tracking |
| 20 | +- **Admin controls** - Admins can manage other users (future feature) |
| 21 | + |
| 22 | +### 🛡️ Access Control |
| 23 | +- **Protected endpoints** - All container operations require authentication |
| 24 | +- **Optional authentication** - Can be disabled for development |
| 25 | +- **Role-based permissions** - Different access levels for admin vs user |
| 26 | +- **CORS protection** - Restricted origins in production |
| 27 | + |
| 28 | +## Default Credentials |
| 29 | + |
| 30 | +**⚠️ IMPORTANT: Change these immediately after first login!** |
| 31 | + |
| 32 | +- **Username:** `admin` |
| 33 | +- **Password:** `admin` |
| 34 | + |
| 35 | +## Configuration |
| 36 | + |
| 37 | +### Environment Variables |
| 38 | + |
| 39 | +```bash |
| 40 | +# Enable/disable authentication |
| 41 | +AUTH_ENABLED=true |
| 42 | + |
| 43 | +# JWT configuration |
| 44 | +JWT_SECRET=your-super-secret-key-change-this |
| 45 | +JWT_EXPIRES_IN=24h |
| 46 | + |
| 47 | +# Default admin password (only used on first setup) |
| 48 | +DEFAULT_ADMIN_PASSWORD=admin |
| 49 | +``` |
| 50 | + |
| 51 | +### Docker Compose |
| 52 | + |
| 53 | +```yaml |
| 54 | +environment: |
| 55 | + - AUTH_ENABLED=true |
| 56 | + - JWT_SECRET=${JWT_SECRET:-homelabarr-change-this-secret} |
| 57 | + - JWT_EXPIRES_IN=24h |
| 58 | + - DEFAULT_ADMIN_PASSWORD=${DEFAULT_ADMIN_PASSWORD:-admin} |
| 59 | +``` |
| 60 | +
|
| 61 | +## API Endpoints |
| 62 | +
|
| 63 | +### Authentication Routes |
| 64 | +
|
| 65 | +- `POST /api/auth/login` - User login |
| 66 | +- `GET /api/auth/me` - Get current user info |
| 67 | +- `POST /api/auth/change-password` - Change user password |
| 68 | +- `POST /api/auth/register` - Create new user (admin only) |
| 69 | +- `GET /api/auth/users` - List all users (admin only) |
| 70 | + |
| 71 | +### Protected Routes |
| 72 | + |
| 73 | +All container management endpoints require authentication when `AUTH_ENABLED=true`: |
| 74 | + |
| 75 | +- `/api/containers/*` - Container operations |
| 76 | +- `/api/deploy` - Application deployment |
| 77 | +- `/api/ports/*` - Port management |
| 78 | + |
| 79 | +## Frontend Components |
| 80 | + |
| 81 | +### Authentication UI |
| 82 | +- **LoginModal** - Secure login form with validation |
| 83 | +- **UserMenu** - User profile dropdown with logout |
| 84 | +- **UserSettings** - Password change and user management |
| 85 | +- **AuthStatus** - Authentication status indicator |
| 86 | + |
| 87 | +### Security Features |
| 88 | +- **Automatic token refresh** - Handles expired tokens gracefully |
| 89 | +- **Secure storage** - Tokens stored in localStorage with validation |
| 90 | +- **Error handling** - Clear feedback for authentication errors |
| 91 | +- **Loading states** - Visual feedback during auth operations |
| 92 | + |
| 93 | +## Security Best Practices |
| 94 | + |
| 95 | +### Production Deployment |
| 96 | +1. **Change default credentials** immediately |
| 97 | +2. **Use strong JWT secret** (32+ random characters) |
| 98 | +3. **Set secure CORS origins** (no wildcards) |
| 99 | +4. **Use HTTPS** in production |
| 100 | +5. **Regular password updates** for all users |
| 101 | + |
| 102 | +### Password Requirements |
| 103 | +- Minimum 6 characters (configurable) |
| 104 | +- Bcrypt hashing with salt rounds: 12 |
| 105 | +- No password reuse validation (future feature) |
| 106 | + |
| 107 | +### Token Security |
| 108 | +- JWT tokens expire after 24 hours (configurable) |
| 109 | +- Tokens include user ID, username, and role |
| 110 | +- Automatic cleanup of expired tokens |
| 111 | +- No refresh token implementation (stateless design) |
| 112 | + |
| 113 | +## Troubleshooting |
| 114 | + |
| 115 | +### Common Issues |
| 116 | + |
| 117 | +1. **"Authentication required" errors** |
| 118 | + - Check if `AUTH_ENABLED=true` in environment |
| 119 | + - Verify JWT_SECRET is set |
| 120 | + - Ensure user is logged in |
| 121 | + |
| 122 | +2. **"Invalid token" errors** |
| 123 | + - Token may have expired (24h default) |
| 124 | + - JWT_SECRET may have changed |
| 125 | + - Clear browser storage and re-login |
| 126 | + |
| 127 | +3. **Default admin not created** |
| 128 | + - Check server logs for errors |
| 129 | + - Verify write permissions to `server/config/` |
| 130 | + - Ensure no existing users.json file |
| 131 | + |
| 132 | +### Debug Commands |
| 133 | + |
| 134 | +```bash |
| 135 | +# Check authentication status |
| 136 | +curl http://localhost:3001/health |
| 137 | +
|
| 138 | +# Test login |
| 139 | +curl -X POST http://localhost:3001/auth/login \ |
| 140 | + -H "Content-Type: application/json" \ |
| 141 | + -d '{"username":"admin","password":"admin"}' |
| 142 | +
|
| 143 | +# Check user info (with token) |
| 144 | +curl http://localhost:3001/auth/me \ |
| 145 | + -H "Authorization: Bearer YOUR_TOKEN_HERE" |
| 146 | +``` |
| 147 | + |
| 148 | +## Future Enhancements |
| 149 | + |
| 150 | +- **Multi-factor authentication** (2FA/TOTP) |
| 151 | +- **OAuth integration** (Google, GitHub, etc.) |
| 152 | +- **Advanced user management** (admin UI) |
| 153 | +- **Audit logging** (user actions tracking) |
| 154 | +- **Password policies** (complexity requirements) |
| 155 | +- **Session management** (active sessions, force logout) |
| 156 | +- **API key authentication** (for automation) |
| 157 | + |
| 158 | +## Development |
| 159 | + |
| 160 | +### Disabling Authentication |
| 161 | + |
| 162 | +For development, you can disable authentication: |
| 163 | + |
| 164 | +```bash |
| 165 | +AUTH_ENABLED=false |
| 166 | +``` |
| 167 | + |
| 168 | +This allows unrestricted access to all endpoints. |
| 169 | + |
| 170 | +### Testing Authentication |
| 171 | + |
| 172 | +The system includes comprehensive error handling and validation. Test with: |
| 173 | + |
| 174 | +- Invalid credentials |
| 175 | +- Expired tokens |
| 176 | +- Missing tokens |
| 177 | +- Role-based access restrictions |
0 commit comments