Gateway Service Reference
This reference documentation provides comprehensive details about the gateway service, its request routing capabilities, CORS handling, and integration with other Vidos services.
Overview
The gateway service acts as an intelligent HTTP router and proxy for Vidos services, providing a unified entry point for client applications while handling service discovery, authentication, and request forwarding. Rather than processing credentials or performing verification directly, the gateway coordinates access to specialized Vidos services through configurable path-based routing.
The gateway handles cross-origin resource sharing (CORS) for web applications, manages service-to-service authentication, and provides seamless request forwarding to configured service instances. By centralizing routing and access control, it enables secure and efficient communication between client applications and the distributed Vidos service architecture.
Request Routing
The gateway implements path-based request routing that maps URL paths to specific Vidos service instances:
| Component | Description | Processing Type |
|---|---|---|
| Path Resolution | Extracts the first path segment for route lookup | Direct processing |
| Service Discovery | Maps paths to configured service instances | Configuration lookup |
| Request Forwarding | Proxies requests to target services | HTTP forwarding |
| Response Streaming | Streams responses back to clients | Direct passthrough |
The gateway processes incoming requests by extracting the first path segment, looking up the corresponding service configuration, and forwarding the remaining path to the target service instance. This architecture enables flexible service composition while maintaining clean URL structures.
Supported Service Types
The gateway can route requests to any of the core Vidos services based on configuration:
| Service Type | Description | Use Case | Authentication Support |
|---|---|---|---|
| Authorizer | OpenID4VP authorization workflows | Credential presentation flows | Account + Managed roles |
| Resolver | DID document resolution | Identity verification | Account + Managed roles |
| Verifier | Cryptographic verification | Signature and proof validation | Account + Managed roles |
| Validator | Structural credential validation | Schema and format validation | Account + Managed roles |
Each service type can be configured with multiple instances, allowing for specialized routing based on different use cases, security requirements, or performance characteristics.
Cross-Origin Resource Sharing (CORS)
The gateway provides comprehensive CORS support for web applications accessing Vidos services:
| CORS Feature | Description | Configuration Options | Security Considerations |
|---|---|---|---|
| Origin Control | Restricts requests by origin domain | Whitelist, wildcards | Prevents unauthorized domains |
| Method Filtering | Controls allowed HTTP methods | GET, POST, PUT, PATCH, DELETE | Limits attack surface |
| Header Management | Configures allowed/exposed headers | Custom headers, credentials | Controls data exposure |
| Credential Handling | Manages cookie and auth credentials | Enable/disable flags | Authentication integration |
CORS configuration applies to all routed services, providing consistent cross-origin behavior across the entire Vidos service ecosystem while maintaining security boundaries.
Service Authentication
The gateway handles service-to-service authentication automatically when forwarding requests:
Authentication Headers
The gateway adds authentication and context headers to all forwarded requests:
- Service Role Authentication: Uses configured service roles for authorization
- Account Context: Includes account ID for multi-tenant isolation
- Regional Context: Provides regional information for compliance
- Resource Context: Specifies target service and instance details
- Origin Tracking: Maintains original request context for auditing
Service Role Types
The gateway supports both account-owned and managed service roles:
- Account Roles: Custom roles defined by the account owner
- Managed Roles: Predefined roles managed by Vidos platform
For details on service role configuration and management, see the Service Roles Reference.
API Reference
The gateway service exposes management APIs for instance and configuration management:
Instance Management
- Create Instance: Deploy new gateway instances with custom configurations
- Update Instance: Modify existing gateway routing and CORS settings
- Delete Instance: Remove gateway instances and clean up resources
- Get Instance: Retrieve detailed instance information and status
- List Instances: View all gateway instances for an account
Configuration Management
- Create Configuration: Define reusable gateway configurations
- Update Configuration: Modify routing paths and service mappings
- Delete Configuration: Remove configuration templates
- Get Configuration: Retrieve specific configuration details
- List Configurations: View all available configurations
Request Processing Flow
When the gateway receives a request, it follows this processing sequence:
- Status Verification: Confirms the gateway instance is running
- CORS Handling: Processes preflight requests and applies CORS headers
- Path Extraction: Extracts the first path segment for routing lookup
- Service Resolution: Maps the path to a configured service instance
- Authentication Setup: Adds service-to-service authentication headers
- Request Forwarding: Proxies the request to the target service
- Response Streaming: Streams the service response back to the client
This flow ensures secure, efficient request routing while maintaining full HTTP compatibility and preserving request/response semantics.
Configuration
The gateway service configuration controls routing behavior, CORS policies, and service integration. Key configuration areas include:
- CORS Configuration: Controls cross-origin access policies for web applications
- Path Configuration: Maps URL paths to specific service instances and authentication
- Service Instance References: Specifies target services and authentication roles
For comprehensive information about configuring the gateway service, including all available options, routing examples, CORS settings, and service integration patterns, see the Configuration Reference.
Service Integration
The gateway integrates with all Vidos services through configurable routing paths:
Authorizer Integration
Route credential presentation and authorization requests to authorizer instances for OpenID4VP processing. The gateway forwards authentication flows while maintaining session context and security boundaries.
For details on authorizer capabilities, see the Authorizer Service Documentation.
Resolver Integration
Route DID resolution requests to resolver instances for identity document retrieval. The gateway enables efficient DID resolution while providing caching and load balancing capabilities.
For details on resolution processes, see the Resolver Service Documentation.
Verifier Integration
Route verification requests to verifier instances for cryptographic validation. The gateway coordinates signature verification and trust validation workflows.
For details on verification processes, see the Verifier Service Documentation.
Validator Integration
Route validation requests to validator instances for structural and content validation. The gateway enables schema validation and compliance checking workflows.
For details on validation processes, see the Validator Service Documentation.
Security Considerations
The gateway implements several security measures for safe request routing:
Request Sanitization
The gateway removes potentially dangerous headers from forwarded requests:
- Host Headers: Prevents host header injection attacks
- Forwarded Headers: Removes potentially spoofed forwarding information
- Proxy Headers: Strips proxy-specific headers that could leak information
Service Isolation
Each routed service operates with isolated authentication and context:
- Service Role Authentication: Each service receives appropriate authentication tokens
- Account Isolation: Multi-tenant boundaries are maintained across all services
- Resource Scoping: Services only access their designated resources
CORS Security
CORS configuration provides defense against cross-origin attacks:
- Origin Validation: Restricts requests to authorized domains
- Credential Protection: Controls when credentials are included in requests
- Header Filtering: Limits exposed response headers to prevent information leakage
Performance Characteristics
The gateway is designed for high-performance request routing with minimal latency:
Request Processing
- Streaming Responses: Responses are streamed directly to clients without buffering
- Connection Reuse: HTTP connections to backend services are reused efficiently
- Minimal Overhead: Routing decisions use fast path lookups with minimal processing
Scalability
- Stateless Design: Gateway instances are stateless and can be scaled horizontally
- Service Discovery: Dynamic service instance resolution supports scaling backend services
- Load Distribution: Multiple gateway instances can handle traffic distribution
Additional Resources
- Gateway Configuration Reference - Complete configuration options and routing examples
- Service Instances Reference - Service instance configuration patterns
- Service Roles Reference - Authentication and authorization configuration
- CORS Configuration Reference - Cross-origin resource sharing settings
- Authorizer Service Documentation - For authorization and presentation workflows
- Resolver Service Documentation - For DID resolution capabilities
- Verifier Service Documentation - For verification processes
- Validator Service Documentation - For validation processes
- Understanding Vidos Services - Service architecture and composition patterns