DEPLOYMENT_NOTES.md

Deployment Notes - Bearer Token Authentication & External Job ID Features

Overview

This document outlines the changes made to support JWT Bearer Token Authentication and External Job ID functionality in the audio-extractor microservice.

Required Changes Made

1. Dependencies (requirements.txt)

✅ UPDATED - Added testing dependencies:

# Testing (for development and CI)
pytest==7.4.3
pytest-asyncio==0.21.1

Note: All authentication features use Python standard library modules only:

• base64 - JWT token parsing
• json - JWT payload parsing
• re - Input validation regex

2. Dockerfile Updates

✅ UPDATED - Added required environment variables:

# Authentication and N8N Configuration
ENV ENFORCE_AUTHENTICATION=true
ENV ENABLE_EXTERNAL_JOB_IDS=true
ENV JWT_VALIDATION_STRICT=false
ENV N8N_BASE_URL=http://localhost:5678
ENV N8N_TOKEN=default-token-change-me
ENV N8N_TIMEOUT=30

3. Environment Variables Required

⚠️ REQUIRED for Production:

• N8N_TOKEN - MUST be set to actual N8N service token

Optional (have defaults):

• ENFORCE_AUTHENTICATION=true - Enable/disable authentication requirement
• ENABLE_EXTERNAL_JOB_IDS=true - Enable/disable external job ID feature
• JWT_VALIDATION_STRICT=false - Enable stricter JWT validation if needed
• N8N_BASE_URL=http://localhost:5678 - N8N service URL
• N8N_TIMEOUT=30 - N8N request timeout in seconds

Deployment Checklist

Before Deployment:

• Set N8N_TOKEN environment variable to actual N8N service token
• Update N8N_BASE_URL to point to actual N8N instance
• Configure authentication settings (ENFORCE_AUTHENTICATION)
• Review JWT validation settings (JWT_VALIDATION_STRICT)

Docker Deployment:

# Option 1: Environment file
docker run -d \
  --env-file .env \
  -p 7860:7860 \
  audio-extractor:latest

# Option 2: Direct environment variables  
docker run -d \
  -e N8N_TOKEN=your-actual-n8n-token \
  -e N8N_BASE_URL=https://your-n8n-instance.com \
  -e ENFORCE_AUTHENTICATION=true \
  -p 7860:7860 \
  audio-extractor:latest

Kubernetes Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: audio-extractor
spec:
  template:
    spec:
      containers:
      - name: audio-extractor
        image: audio-extractor:latest
        env:
        - name: N8N_TOKEN
          valueFrom:
            secretKeyRef:
              name: audio-extractor-secrets
              key: n8n-token
        - name: N8N_BASE_URL
          value: "https://your-n8n-instance.com"
        - name: ENFORCE_AUTHENTICATION
          value: "true"

API Changes

Breaking Changes:

🚨 Authentication now required for these endpoints:

• POST /api/v1/extract - Requires Authorization: Bearer <token> header
• GET /api/v1/jobs/{job_id} - Requires Authorization: Bearer <token> header
• GET /api/v1/jobs/{job_id}/download - Requires Authorization: Bearer <token> header

Backwards Compatibility:

✅ Public endpoints (no auth required):

• GET /api/v1/info - API information
• GET /api/v1/health - Health check

New Features:

✅ External Job ID support:

• Optional job_id parameter in extraction requests
• External job ID included in status responses
• Proper validation and uniqueness constraints

✅ Enhanced N8N Integration:

• Bearer tokens forwarded to N8N webhooks
• Secure error handling without token leakage
• Graceful failure handling

Testing

Run Tests:

# All tests
pytest

# Integration tests only
pytest tests/integration/

# Authentication tests only  
pytest tests/integration/test_authentication_flow.py

# N8N integration tests
pytest tests/integration/test_n8n_integration.py

Test Coverage:

• ✅ 100+ unit tests covering all components
• ✅ Integration tests for complete workflows
• ✅ Backwards compatibility verification
• ✅ Performance and security testing
• ✅ Error scenario coverage

Migration Guide for Existing Clients

Option 1: Gradual Migration (Recommended)

1. Deploy new version with ENFORCE_AUTHENTICATION=false
2. Update clients to include Bearer tokens
3. Test thoroughly
4. Enable authentication: ENFORCE_AUTHENTICATION=true

Option 2: Full Migration

1. Update all clients to include Bearer tokens
2. Deploy with ENFORCE_AUTHENTICATION=true

Client Updates Required:

// Before (no auth)
fetch('/api/v1/extract', {
  method: 'POST',
  body: formData
})

// After (with auth)
fetch('/api/v1/extract', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + jwtToken
  },
  body: formData
})

Security Notes

JWT Token Requirements:

• Must have 3 parts separated by dots (header.payload.signature)
• Structure validation only (no signature verification by default)
• Tokens are redacted in all logs for security

External Job ID Requirements:

• Optional field (backwards compatible)
• 1-50 characters
• Alphanumeric, underscores, and hyphens only
• Must be unique across all active jobs

Security Features:

• ✅ Secure token logging with redaction
• ✅ Input validation and sanitization
• ✅ Proper HTTP status codes and error messages
• ✅ N8N integration doesn't leak sensitive data

Monitoring & Health Checks

Health Check Endpoint:

• GET /api/v1/health - Public endpoint (no auth required)
• Returns: {"status": "healthy", "service": "audio-extractor-api"}
• Used by Docker health check and load balancers

Error Monitoring:

• Enhanced error response format with error codes
• Structured logging with sensitive data redaction
• N8N notification failures are logged but don't break job processing

Support

For issues related to:

• Authentication: Check JWT token format and ENFORCE_AUTHENTICATION setting
• External Job IDs: Verify format validation and uniqueness constraints
• N8N Integration: Check N8N_TOKEN and N8N_BASE_URL configuration
• Performance: Review test results in tests/integration/ directory