# Authentication Security Guide ## Overview This document explains the authentication security improvements implemented in Issue #28 to ensure that when authentication is enabled, login is forced and only explicitly public endpoints are accessible without authentication. ## Security Changes ### 1. Tightened Default Public Paths When authentication is enabled, only the following endpoints are public by default: - `/api/health` - Health check endpoint - `/api/status` - Basic server status The following endpoints now require authentication when auth is enabled: - `/api/models` - Model discovery and listing - `/api/models/types` - Model type information - `/api/models/directories` - Model directory information - `/api/samplers` - Sampling methods - `/api/schedulers` - Scheduler options - `/api/parameters` - Generation parameters - `/api/queue/status` - Queue status - `/api/queue/job/{id}` - Job status ### 2. Authentication-First Approach The authentication middleware now follows an "authentication-first" approach: 1. **Authentication Disabled**: All endpoints are accessible (no authentication required) 2. **Authentication Enabled**: Only explicitly public endpoints are accessible without authentication 3. **All Other Endpoints**: Require valid authentication ### 3. Configurable Public Paths Administrators can now customize which endpoints remain public using the `--public-paths` command line option: ```bash # Default behavior (only health and status are public) ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt # Custom public paths ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --public-paths "/api/health,/api/status,/api/models" # Make all endpoints public (not recommended for production) ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --public-paths "/" ``` ## Command Line Options ### New Option - `--public-paths `: Comma-separated list of public paths that don't require authentication - Default: `/api/health,/api/status` when auth is enabled - Example: `--public-paths "/api/health,/api/status,/api/models"` ### Existing Authentication Options - `--auth `: Authentication method (none, jwt, api-key, unix, pam, optional) - `--jwt-secret `: JWT secret key - `--jwt-expiration `: JWT token expiration time - `--enable-guest-access`: Allow unauthenticated guest access - `--pam-service-name `: PAM service name - `--auth-data-dir `: Directory for authentication data ## Security Considerations ### 1. Default Secure Configuration The default configuration is now secure by default: - When authentication is enabled, only essential health/status endpoints are public - All model discovery and generation endpoints require authentication - This prevents unauthorized access to model information and generation capabilities ### 2. Public Path Configuration When configuring custom public paths: - **Minimum Exposure**: Only make endpoints public that are absolutely necessary - **Health Checks**: Health and status endpoints are typically safe to make public - **Model Information**: Consider whether model discovery should be public in your environment - **API Documentation**: If you have API documentation endpoints, consider their exposure ### 3. Authentication Methods Different authentication methods provide different security levels: - **JWT**: Token-based authentication with configurable expiration - **API Key**: Simple key-based authentication for service-to-service communication - **PAM**: Integration with system authentication (recommended for enterprise) - **Unix**: Basic Unix authentication (less secure, consider PAM instead) ### 4. Network Security Authentication is only one layer of security: - **HTTPS**: Always use HTTPS in production environments - **Firewall**: Configure firewall rules to restrict access - **Network Segmentation**: Consider placing the server behind a reverse proxy - **Monitoring**: Monitor authentication attempts and access patterns ## Migration Guide ### From Previous Versions If you're upgrading from a previous version: 1. **Review Public Endpoints**: Check if your applications rely on previously public endpoints 2. **Update Client Applications**: Ensure client applications handle authentication properly 3. **Configure Public Paths**: Use `--public-paths` if you need to maintain previous behavior temporarily 4. **Test Authentication**: Verify that all protected endpoints properly require authentication ### Example Migration Scenarios #### Scenario 1: Public API Documentation If you need to keep API documentation public: ```bash ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --public-paths "/api/health,/api/status,/api/docs,/api/openapi.json" ``` #### Scenario 2: Internal Tool Access If you have internal monitoring tools that need access: ```bash ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --public-paths "/api/health,/api/status,/api/queue/status" ``` #### Scenario 3: Development Environment For development where you want more permissive access: ```bash ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --public-paths "/api/health,/api/status,/api/models,/api/samplers" ``` ## Testing Authentication ### Testing Protected Endpoints ```bash # Test without authentication (should fail) curl -i http://localhost:8080/api/models # Test with authentication curl -i -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/models ``` ### Testing Public Endpoints ```bash # Test public endpoint (should succeed) curl -i http://localhost:8080/api/health ``` ## Best Practices 1. **Principle of Least Privilege**: Only make endpoints public that are absolutely necessary 2. **Regular Security Reviews**: Periodically review your authentication configuration 3. **Monitor Access**: Log and monitor authentication attempts 4. **Use Strong Authentication**: Prefer JWT or PAM over simpler methods 5. **Secure Communication**: Always use HTTPS in production 6. **Token Management**: Implement proper token expiration and refresh mechanisms ## Troubleshooting ### Common Issues 1. **401 Unauthorized on Previously Public Endpoints** - Cause: Endpoints now require authentication - Solution: Add authentication to client or use `--public-paths` to make endpoint public 2. **Authentication Not Working** - Cause: Authentication method not properly configured - Solution: Check authentication configuration and logs 3. **Public Paths Not Working** - Cause: Incorrect path format in `--public-paths` - Solution: Ensure paths start with `/` and are comma-separated ### Debugging Enable verbose logging to debug authentication issues: ```bash ./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --verbose ``` Check the logs for authentication-related messages and failed authentication attempts.