This guide covers setting up the client reverse proxy by configuring nginx manually. For a faster, environment-variable-driven approach, see Docker Setup.
Nginx Configuration
The configuration is split into three server blocks:
| Server Block | Purpose | Access Control |
|---|
| Public API | SDK-facing endpoints | Open (public) |
| Internal API | Backend middleware endpoints | IP whitelisted (middleware subnet) |
| Dashboard | Admin dashboard access | IP whitelisted (office / VPN) |
http {
# Public API Server - Publicly accessible SDK endpoints
server {
listen 443 ssl;
server_name uaekyc-api.clientDomain.ae;
ssl_certificate /path/to/ssl_certificate;
ssl_certificate_key /path/to/ssl_certificate_key;
access_log /var/log/nginx/uaekyc-api.log json_combined;
location ~ ^/otk-service/(journey-handshake|update-journey|sdk-error)$ {
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE, PATCH' always;
add_header 'Access-Control-Allow-Headers' '*' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
proxy_pass https://<UAEKYC_API_FQDN>;
proxy_set_header Host <UAEKYC_API_FQDN>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_hide_header 'Access-Control-Allow-Origin';
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE, PATCH' always;
add_header 'Access-Control-Allow-Headers' '*' always;
add_header 'Access-Control-Max-Age' 1728000;
add_header 'Content-Length' 0;
add_header 'Content-Type' 'text/plain; charset=UTF-8';
return 204;
}
}
location / {
return 403;
}
}
# Internal API Server - Restricted endpoints with IP whitelisting
server {
listen 443 ssl;
server_name uaekyc-internal-api.clientDomain.ae;
ssl_certificate /path/to/ssl_certificate;
ssl_certificate_key /path/to/ssl_certificate_key;
access_log /var/log/nginx/uaekyc-internal-api.log json_combined;
allow <PRIVATE_MIDDLEWARE_SUBNET>;
deny all;
location ~ ^/otk-service/(create-journey-url|v2/journey-details/[^/]+|customer-details/[^/]+)$ {
proxy_pass https://<UAEKYC_API_FQDN>;
proxy_set_header Host <UAEKYC_API_FQDN>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location / {
return 403;
}
}
# Internal Dashboard Access - Restricted to Office/VPN IPs
server {
listen 443 ssl;
server_name uaekyc-dash.clientDomain.ae;
ssl_certificate /path/to/ssl_certificate;
ssl_certificate_key /path/to/ssl_certificate_key;
allow <INTERNAL_OFFICE_OR_VPN_IP>;
deny all;
access_log /var/log/nginx/uaekyc-dashboard.log json_combined;
location = / {
proxy_pass https://<UAEKYC_DASH_FQDN>;
proxy_set_header Host <UAEKYC_DASH_FQDN>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location ~ ^/(api|sandbox-api|dashboard|assets|svg|login|logout|favicon.ico) {
proxy_pass https://<UAEKYC_DASH_FQDN>;
proxy_set_header Host <UAEKYC_DASH_FQDN>;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location / {
return 403;
}
}
}
Placeholders to Replace
| Placeholder | Replace With |
|---|
uaekyc-api.clientDomain.ae | Your public API domain |
uaekyc-internal-api.clientDomain.ae | Your internal API domain |
uaekyc-dash.clientDomain.ae | Your dashboard domain |
<UAEKYC_API_FQDN> | UAE KYC API endpoint (provided during onboarding) |
<UAEKYC_DASH_FQDN> | UAE KYC Dashboard endpoint (provided during onboarding) |
<PRIVATE_MIDDLEWARE_SUBNET> | Your middleware server IP range |
<INTERNAL_OFFICE_OR_VPN_IP> | Your office or VPN IP address |
/path/to/ssl_certificate | Path to your SSL certificate file |
/path/to/ssl_certificate_key | Path to your SSL private key file |
SSL / HTTPS
SSL is configured per server block using the ssl_certificate and ssl_certificate_key directives:
server {
listen 443 ssl;
server_name uaekyc-api.clientDomain.ae;
ssl_certificate /path/to/ssl_certificate;
ssl_certificate_key /path/to/ssl_certificate_key;
# Recommended: restrict protocols
ssl_protocols TLSv1.3;
# ...
}
Important Security Notice
Critical: This Nginx configuration is not holistic in nature and serves as a basic starting point only. Clients are required to implement comprehensive security mechanisms over the public proxy setup.
Production Security Requirements
For production deployment, clients must implement the following security layers:
Web Application Firewall (WAF)
- Layer 7 Protection: DDoS protection, SQL injection, XSS, and OWASP Top 10 vulnerabilities
- Bot Detection: Automated bot protection and rate limiting
- Geographic Filtering: IP-based country/region restrictions as needed
- Custom Rules: Business-specific security rules and threat intelligence
Monitoring & Logging
- Real-time Monitoring: 24/7 security event monitoring and alerting
- Comprehensive Logging: All request/response logs with security context
- SIEM Integration: Security Information and Event Management system integration
- Performance Monitoring: Response times, error rates, and availability metrics
Additional Security Optimizations
- Security Headers: HSTS, CSP, X-Frame-Options, X-Content-Type-Options
- Rate Limiting: Advanced rate limiting with burst protection
- SSL/TLS Hardening: Modern cipher suites, OCSP stapling, certificate pinning
- Request Validation: Size limitations, timeout configurations, input validation
- IP Management: Dynamic IP whitelisting/blacklisting capabilities
Reverse Proxy Compatibility
Flexibility: Any public proxy or reverse proxy solution is acceptable as long as it meets the following requirements:
Compatible Solutions
- Nginx: Recommended with proper security enhancements
- Apache HTTP Server: With mod_proxy and security modules
- HAProxy: With appropriate load balancing and security configurations
- Cloud-based Solutions: AWS Application Load Balancer, Azure Application Gateway, Cloudflare
Critical Requirements for All Proxy Solutions
Binary Payload Integrity: The proxy solution must not interfere with binary payloads being transmitted by the SDK.
-
No Buffering During Serialization/Deserialization:
- Disable proxy-level buffering for SDK endpoints
- Ensure direct pass-through of binary data
- Maintain content integrity during transmission
-
Content-Type Preservation:
- Preserve original Content-Type headers
- Do not modify multipart/form-data boundaries
- Maintain binary encoding integrity
Strongly Discouraged Solutions
Not Recommended: Flask or Java-based application servers as reverse proxies are strongly not advised for the following reasons:
- Memory Limitations: Poor handling of large binary payloads
- Performance Issues: Single-threaded nature affects concurrent requests
- Serialization Problems: Python object serialization interferes with binary data
- Limited Security Features: Lacks enterprise-grade security capabilities
Java-based Application Servers (Tomcat, Jetty, etc.):
- Object Serialization: Automatic serialization can corrupt binary payloads
- Memory Overhead: High memory consumption for binary data handling
- Complex Configuration: Difficult to configure for pure proxy operations
- Performance Bottlenecks: Additional processing layers affect response times
Business-Specific Customizations
Each client implementation should include:
- Custom Rate Limiting: Based on business traffic patterns
- Geographic Restrictions: Compliance with regional regulations
- Industry-Specific Security: Healthcare, financial, government requirements
- Integration Security: API gateway, authentication proxy, audit requirements
- Compliance Monitoring: SOC 2, ISO 27001, PCI DSS as applicable
Ensure your security, DevOps, and compliance teams review and enhance this configuration with business-specific requirements before production deployment.
