stable-diffusion.cpp-rest/AUTHENTICATION_SECURITY_GUIDE.md

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:

# 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 <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 <method>: Authentication method (none, jwt, api-key, unix, pam, optional)
• --jwt-secret <secret>: JWT secret key
• --jwt-expiration <minutes>: JWT token expiration time
• --enable-guest-access: Allow unauthenticated guest access
• --pam-service-name <name>: PAM service name
• --auth-data-dir <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:

./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:

./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:

./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

# 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

# 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:

./stable-diffusion-rest --models-dir /data/SD_MODELS --auth jwt --verbose

Check the logs for authentication-related messages and failed authentication attempts.