API Key Authentication (Lightweight Alternative)

[bburda]

Summary

Implement simple API key authentication as a lightweight alternative to full JWT/OAuth2 for simpler deployments.

---

Background

While JWT with RBAC provides comprehensive security, some deployments need simpler authentication:

• Internal/isolated networks
• Development and testing environments
• Single-user scenarios
• Quick prototyping
• Machine-to-machine communication

---

Proposed Solution

1. Configuration

ros2_medkit_gateway:
  ros__parameters:
    auth:
      # Simple API key mode (alternative to JWT)
      api_keys:
        enabled: false
        keys:
          - key: "your-secret-api-key-here"
            name: "developer-1"
            role: "admin"
          - key: "readonly-key"
            name: "monitoring-system"
            role: "viewer"

        # Where to look for API key
        header_name: "X-API-Key"
        query_param_name: "api_key"  # Optional, less secure

2. Usage

Clients include the API key in requests:

# Via header (preferred)
curl -H "X-API-Key: your-secret-api-key-here" http://localhost:8080/api/v1/areas

# Via query parameter (less secure, for debugging only)
curl "http://localhost:8080/api/v1/areas?api_key=your-key"

3. API Key Management

• Keys should be generated securely (minimum 32 characters, cryptographically random)
• Support key rotation without restart
• Log key usage for auditing

---

Implementation Tasks

• Add API key configuration parsing
• Implement API key validation middleware
• Support header and query parameter authentication
• Apply same RBAC permissions as JWT roles
• Add key generation helper script
• Unit and integration tests
• Documentation with security recommendations

---

Acceptance Criteria

• Valid API key grants access per assigned role
• Invalid/missing API key returns 401
• Works alongside or instead of JWT authentication
• Keys can be rotated without restart (future: hot reload)
• Clear logging of API key usage (without exposing keys)

---

Security Recommendations

Document these best practices:

• Never commit API keys to version control
• Use environment variables or secure vaults for key storage
• Prefer header-based authentication over query parameters
• Rotate keys periodically
• Use different keys per client/service for auditability