ReportProxy Service

Overview

The ReportProxy is a sophisticated Azure Function microservice that serves as a secure proxy for accessing reports and files stored in Azure Blob Storage. This service provides authenticated and authorized access to publisher reports, configuration files, and other blob storage resources through a RESTful API with role-based access control and publisher-specific authorization.

Business Purpose

This service serves as a secure gateway for report and file access that: - Provides authenticated access to reports stored in Azure Blob Storage - Implements role-based access control (admin, user roles) - Enforces publisher-specific authorization for data isolation - Supports file upload and deletion operations with proper authorization - Handles report retrieval with automatic file discovery and content encoding - Manages configuration file access across different environments - Provides secure proxy functionality for blob storage operations

Architecture

Service Type

Platform: Azure Functions (Containerized Kubernetes Microservice)
Runtime: Node.js with Express.js framework
Trigger: HTTP Trigger (Anonymous with JWT authentication)
Pattern: Secure Proxy with Role-Based Access Control

Key Components

graph TD
    A[HTTP Request] --> B[Express Router]
    B --> C[CORS Middleware]
    C --> D[JWT Authentication]
    D --> E{Valid Token?}

    E -->|No| F[401 Unauthorized]
    E -->|Yes| G[Role Authorization]

    G --> H{Valid Role?}
    H -->|No| I[403 Forbidden]
    H -->|Yes| J[Publisher Authorization]

    J --> K{Publisher Access?}
    K -->|No| L[403 Forbidden]
    K -->|Yes| M[Route Handler]

    M --> N{Operation Type?}
    N -->|GET| O[File Download]
    N -->|POST| P[File Upload]
    N -->|DELETE| Q[File Deletion]

    O --> R[Blob Discovery]
    R --> S[Azure Blob Storage]
    S --> T[Content Retrieval]
    T --> U[Base64 Encoding]
    U --> V[Response]

    P --> W[Multipart Processing]
    W --> X[File Upload to Blob]
    X --> Y[Upload Response]

    Q --> Z[File Deletion from Blob]
    Z --> AA[Delete Response]

    BB[Cosmos DB] --> J
    CC[JWT Secret] --> D

Authentication and Authorization

JWT Authentication

Token Format: Bearer token in Authorization header
Token Validation: JWT signature verification using configured secret
Claims Extraction: User roles and publisher organization from token claims

Role-Based Authorization

Admin Role: Full access to all operations and publishers
User Role: Limited access based on publisher association
Role Validation: Intersection-based role matching

Publisher Authorization

Publisher Isolation: Users can only access their own publisher data
Global Access: Admin users with '*' publisher ID have global access
Vendor Validation: Cross-reference with vendor database for authorization

API Specification

Endpoints

Report Access (GET)

GET /:container/:prefix/:reportType/:publisherId/*
GET /:container/configuration/*
GET /:container/:prefix/:reportType/*

File Management

POST /:container/:prefix/:fileType/:id/upload
DELETE /:container/:prefix/:fileType/:id/:fileName

Request Parameters

Path Parameters

container: Azure Blob Storage container name
prefix: Report/file prefix for organization
reportType: Type of report being accessed
publisherId: Publisher identifier for authorization
fileType: Type of file being uploaded/deleted
id: Unique identifier for file operations
fileName: Name of file to delete

Query Parameters

trimQSParams: Boolean flag to remove query parameters from blob names
partnerKey: Alternative publisher key for authorization
platform: Platform identifier for multi-platform support

Response Formats

Successful File Retrieval

{
    "content": "base64-encoded-file-content",
    "lastModified": "2023-01-01T00:00:00.000Z"
}

File Upload Response

{
    "message": "File uploaded successfully",
    "fileName": "uploaded-file-name",
    "size": 1024,
    "uploadTime": "2023-01-01T00:00:00.000Z"
}

Error Response

{
    "error": "Error description",
    "details": "Additional error context"
}

Core Functionality

File Discovery and Retrieval

Blob Name Resolution: Constructs blob path from URL parameters
Prefix Matching: Finds first matching blob with specified prefix
Content Download: Retrieves blob content from Azure Storage
Base64 Encoding: Encodes binary content for JSON response
Metadata Inclusion: Includes last modified timestamp

File Upload Processing

Multipart Parsing: Processes multipart form data uploads
File Validation: Validates uploaded files and metadata
Blob Upload: Stores files in Azure Blob Storage
Batch Processing: Supports multiple file uploads
Response Aggregation: Provides detailed upload results

File Deletion

Path Validation: Validates file path and permissions
Blob Deletion: Removes file from Azure Blob Storage
Result Confirmation: Confirms successful deletion

Key Features

Secure Access: JWT-based authentication with role validation
Publisher Isolation: Strict publisher-based data access control
Automatic Discovery: Intelligent blob discovery with prefix matching
Content Encoding: Base64 encoding for binary file transmission
Multi-file Support: Batch upload and processing capabilities
Error Handling: Comprehensive error handling with detailed responses
CORS Support: Cross-origin resource sharing for web applications

Security Model

Authentication Layer

JWT Validation: Cryptographic signature verification
Token Expiration: Automatic token expiration handling
Secure Headers: Proper authorization header validation

Authorization Layers

Role-Based Access: Admin and user role validation
Publisher Scope: Publisher-specific data access control
Resource Permissions: Fine-grained resource access control

Data Protection

Publisher Isolation: Strict data segregation by publisher
Secure Transmission: HTTPS-only communication
Access Logging: Comprehensive access audit trails

Performance Characteristics

Processing Metrics

Throughput: ~200 requests per second
Latency: <500ms average response time (excluding blob download)
File Size Limits: Supports files up to 100MB
Concurrent Uploads: Up to 10 simultaneous file uploads

Optimization Features

Streaming Downloads: Efficient blob content streaming
Prefix Matching: Optimized blob discovery algorithms
Connection Pooling: Reused Azure Storage connections
Memory Management: Efficient memory usage for large files

Dependencies

External Services

Azure Blob Storage: Primary file storage backend
Cosmos DB: Publisher and vendor data validation
JWT Service: Token validation and claims extraction

Key NPM Packages

@azure/storage-blob: Azure Blob Storage SDK
express: Web framework for routing and middleware
jsonwebtoken: JWT token validation
multer: Multipart form data processing
cors: Cross-origin resource sharing
lodash: Utility functions

Configuration

Environment-Specific Settings

Development: Development blob storage and JWT secrets
Integration: Integration testing with staging storage
Production: Production storage and security configurations

Key Configuration Elements

Azure Blob Storage connection strings
JWT secret keys for token validation
Cosmos DB connection for publisher validation
CORS configuration for web access

Error Handling

Error Scenarios

Authentication Failures: Invalid or expired JWT tokens
Authorization Failures: Insufficient roles or publisher access
File Not Found: Requested blob doesn't exist
Upload Failures: File upload errors or storage issues
Storage Errors: Azure Blob Storage connectivity issues

Error Response Strategy

HTTP Status Codes: Appropriate status codes for different error types
Detailed Messages: Comprehensive error descriptions
Security Considerations: No sensitive information in error responses
Logging: Full error context for debugging

Monitoring and Observability

Logging

Authentication and authorization events
File access patterns and performance metrics
Error conditions and failure rates
Security-related events and access attempts

Metrics

Request processing rates and response times
Authentication success/failure rates
File upload/download volumes and sizes
Error rates by type and endpoint

This service integrates with the broader Publisher ecosystem: - ReportGenerator: Provides generated reports for proxy access - Publisher Portal: Primary consumer of report proxy services - Authentication Services: JWT token validation and user management - Vendor Management: Publisher and vendor authorization data

Troubleshooting

Common Issues

Authentication Failures: Verify JWT token validity and secret configuration
Authorization Errors: Check user roles and publisher associations
File Not Found: Verify blob paths and container configurations
Upload Failures: Check file size limits and storage permissions
Performance Issues: Monitor blob storage connectivity and response times

Debug Steps

Verify JWT token claims and expiration
Check user roles and publisher authorization
Validate Azure Blob Storage connectivity
Review file paths and container configurations
Monitor storage account performance metrics

Development

Local Development Setup

Clone repository
Install dependencies: npm install
Configure Azure Blob Storage connection
Set up JWT secret configuration
Configure Cosmos DB connection
Run tests: npm test
Start locally: func start

Testing

# Test authentication
curl -H "Authorization: Bearer <jwt-token>" \
  "http://localhost:7071/api/reports/container/config/file.json"

# Test file upload
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -F "file=@test.pdf" \
  "http://localhost:7071/api/reports/container/uploads/document/123/upload"

# Test file deletion
curl -X DELETE -H "Authorization: Bearer <jwt-token>" \
  "http://localhost:7071/api/reports/container/uploads/document/123/test.pdf"

Code Structure

src/index.js: Main Express router and route handlers
src/auth.js: Authentication and authorization middleware
src/blob.js: Azure Blob Storage operations
src/stream.js: Stream processing utilities
src/wrapper-connector.js: Express-to-Azure Functions adapter
config/: Environment-specific configurations