KT Doc-Hub

Appearance

WFS Export Proxy Service ​

Overview ​

The WFS (Web Feature Service) Proxy is a Plack middleware component that proxies WFS requests from clients to AWS-hosted WFS API endpoints. It provides secure, authenticated access to geospatial data while handling authentication, authorization, and configuration injection.

How our WFSProxy Works ​

Architecture Overview ​

WFSProxy operates as middleware in the Plack/PSGI application stack, specifically designed to:

  1. Intercept WFS requests - Captures all requests to /wfs endpoints
  2. Handle authentication - Validates users via Basic Authentication
  3. Sign configuration data - Creates signed tokens containing workspace configuration
  4. Proxy to AWS - Forwards authenticated requests to AWS WFS API endpoints

Request Flow ​

Key Components ​

1. WFSProxy Middleware (server/lib/Plack/Middleware/WFSProxy.pm) ​

Location: /server/lib/Plack/Middleware/WFSProxy.pm

Core Functionality:

  • Path Filtering: Only processes requests to /wfs paths
  • Legacy Bypass: Respects useLegacyWfsService configuration to fall back to legacy WFS implementation
  • Authentication: Uses Plack::Middleware::BasicAuthCheck with configured password file
  • Configuration Injection: Signs workspace configuration data and adds it to request headers
  • Proxying: Uses Plack::App::Proxy to forward requests to AWS endpoints

Key Configuration Values:

  • Drain.config_js.aws_api_domain - Target AWS API domain
  • Drain.config_js.wfs_proxy_secret - Secret key for signing tokens
  • Plugin::Authentication.KaarbonTech.store.file - Password file for Basic Auth
  • useLegacyWfsService - Flag to bypass proxy and use legacy WFS

2. WFSHeaders Middleware (server/lib/Plack/Middleware/WFSHeaders.pm) ​

Location: /server/lib/Plack/Middleware/WFSHeaders.pm

Purpose: Handles CORS (Cross-Origin Resource Sharing) and authentication headers for WFS requests

Key Features:

  • CORS Support: Sets appropriate Access-Control headers based on request origin
  • OPTIONS Handling: Processes preflight OPTIONS requests without authentication
  • Auth Headers: Adds WWW-Authenticate header for 401 responses
  • Dynamic CORS: Dynamically sets Access-Control-Allow-Origin based on request origin

3. Legacy WFS Controller (server/lib/Drain/Controller/WFS.pm) ​

Location: /server/lib/Drain/Controller/WFS.pm

Purpose: Traditional WFS implementation using MapServer for installations not using the proxy

Authentication Flow ​

  1. Request Interception: WFSProxy captures /wfs requests
  2. Basic Auth Check: Uses Plack::Middleware::BasicAuthCheck::check_and_force_basic_auth()
  3. Credential Validation: Validates against configured password file
  4. Header Cleanup: Removes session cookies and authorization headers before proxying
  5. Configuration Signing: Creates signed token with workspace configuration

Configuration Signing Process ​

  • Uses Crypt::JWT to create a JWT token using the secret from Drain.config_js.wfs_proxy_secret

Integration in Application Stack ​

PSGI Configuration (server/drain.psgi:54):

perl
$kt_app = Plack::Middleware::WFSProxy->wrap($kt_app);

The middleware is wrapped around the main Catalyst application, ensuring it processes requests before they reach the main application logic.

Configuration Options ​

Workspace-Level Configuration ​

Many workspace configurations include the useLegacyWfsService flag:

typescript
// Example from workspace config
useLegacyWfsService: true  // Bypasses proxy, uses legacy WFS

System Configuration ​

Key system configuration values:

  • Drain.config_js.aws_api_domain - AWS API endpoint URL
  • Drain.config_js.wfs_proxy_secret - Secret for token signing
  • Drain.installation_type - Installation type (live, devel, etc.)

Security Features ​

  1. Authentication Required: All WFS requests must include valid Basic Auth credentials
  2. Token Signing: Configuration data is cryptographically signed
  3. Header Sanitization: Session cookies and auth headers are removed before proxying
  4. CORS Protection: Dynamic CORS headers prevent unauthorized cross-origin requests
  5. Expiring Tokens: Signed tokens have built-in expiration (default 24 hours)

Error Handling ​

  • 401 Unauthorized: Returns Basic Auth challenge for invalid credentials
  • Legacy Fallback: Automatically falls back to legacy WFS when useLegacyWfsService is true
  • CORS Preflight: Handles OPTIONS requests without authentication requirements
  • server/lib/Plack/Middleware/WFSProxy.pm - Main proxy middleware
  • server/lib/Plack/Middleware/WFSHeaders.pm - CORS and header handling
  • server/lib/Drain/Controller/WFS.pm - Legacy WFS implementation
  • server/drain.psgi - PSGI application configuration