Skip to content

SAS-Implementation-Guide.md

Latest commit

 

History

History
141 lines (109 loc) · 4.03 KB

SAS-Implementation-Guide.md

File metadata and controls

141 lines (109 loc) · 4.03 KB

SAS URL Implementation for Secure Document Download

Overview

This implementation provides secure access to translated documents stored in private Azure Blob Storage using 5-minute expiring SAS (Shared Access Signature) tokens.

How It Works

1. Document Translation Flow

  1. User uploads document for translation
  2. Document gets translated and stored in Azure Blob Storage (private container)
  3. Backend generates a 5-minute SAS URL for the blob
  4. Frontend receives the SAS URL directly in the translation response
  5. User can download directly from Azure Storage using the temporary SAS URL

2. Key Components

Backend Service (DocumentTranslationWebService.cs)

  • GenerateDocumentSasUrlAsync(): Creates 5-minute SAS tokens for blob access
  • Uses BlobSasBuilder with read-only permissions
  • Validates blob existence before generating SAS
  • Comprehensive logging and error handling

Controller (TranslationController.cs)

  • Document translation endpoint now returns SAS URL directly
  • New /api/translation/sas/{documentId} endpoint for on-demand SAS generation
  • Proper error handling for missing documents and invalid IDs

Frontend (app.js)

  • Direct download links using SAS URLs
  • No need for custom download methods - browser handles it natively
  • Shows expiration warning to users

Security Features

✅ Private Storage

  • Blob container uses PublicAccessType.None
  • No public access to any files

✅ Time-Limited Access

  • SAS tokens expire in exactly 5 minutes
  • Read-only permissions
  • Cannot be renewed without server interaction

✅ Authenticated Generation

  • SAS URLs only generated through authenticated API calls
  • Document ownership validated before SAS generation

✅ Audit Trail

  • Comprehensive logging of all SAS generation and access
  • Document access tracking

API Endpoints

POST /api/translation/document

Response:

{
  "translatedDocumentUrl": "https://storage.blob.core.windows.net/translated/blob-name?sp=r&st=...&se=...&sr=b&sig=...",
  "originalFileName": "document.pdf",
  "fromLanguage": "en",
  "toLanguage": "es"
}

GET /api/translation/sas/{documentId}

Response:

{
  "sasUrl": "https://storage.blob.core.windows.net/translated/blob-name?sp=r&st=...&se=...&sr=b&sig=...",
  "expiresInMinutes": 5
}

Configuration Requirements

Azure Storage Account

  • Connection string must be configured in appsettings.json
  • Storage account must support SAS token generation
  • Recommend using Standard_LRS tier for cost efficiency

Example Configuration

{
  "DocumentTranslation": {
    "StorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=yourstorageaccount;AccountKey=yourkey;EndpointSuffix=core.windows.net"
  }
}

Benefits

🚀 Performance

  • Direct downloads from Azure CDN edge locations
  • No server bandwidth usage for file transfers
  • Faster download speeds for users worldwide

🔒 Security

  • No permanent public URLs
  • Time-limited access prevents link sharing abuse
  • Server maintains full control over access

💰 Cost Efficiency

  • Reduced server resource usage
  • Lower bandwidth costs
  • Azure Storage is more cost-effective than server storage

📈 Scalability

  • Downloads don't impact server performance
  • Azure Storage handles high concurrent downloads
  • Global CDN distribution

Testing

Use the provided test files:

  • test-sas.html - Test SAS URL generation
  • test-download.html - Test legacy download functionality

Monitoring

Monitor these metrics:

  • SAS token generation frequency
  • Failed SAS generations (indicates missing documents)
  • Download success rates
  • Token expiration warnings

Error Handling

The implementation handles:

  • Missing documents (404)
  • Expired SAS tokens (automatically handled by Azure)
  • Storage connectivity issues (falls back gracefully)
  • Invalid document IDs (400 Bad Request)

Future Enhancements

Consider implementing:

  • Configurable SAS expiration times
  • User-specific access controls
  • Download analytics and reporting
  • Automatic cleanup of expired documents