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:

ComponentDescriptionProcessing Type
Path ResolutionExtracts the first path segment for route lookupDirect processing
Service DiscoveryMaps paths to configured service instancesConfiguration lookup
Request ForwardingProxies requests to target servicesHTTP forwarding
Response StreamingStreams responses back to clientsDirect 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 TypeDescriptionUse CaseAuthentication Support
AuthorizerOpenID4VP authorization workflowsCredential presentation flowsAccount + Managed roles
ResolverDID document resolutionIdentity verificationAccount + Managed roles
VerifierCryptographic verificationSignature and proof validationAccount + Managed roles
ValidatorStructural credential validationSchema and format validationAccount + 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 FeatureDescriptionConfiguration OptionsSecurity Considerations
Origin ControlRestricts requests by origin domainWhitelist, wildcardsPrevents unauthorized domains
Method FilteringControls allowed HTTP methodsGET, POST, PUT, PATCH, DELETELimits attack surface
Header ManagementConfigures allowed/exposed headersCustom headers, credentialsControls data exposure
Credential HandlingManages cookie and auth credentialsEnable/disable flagsAuthentication 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:

  1. Status Verification: Confirms the gateway instance is running
  2. CORS Handling: Processes preflight requests and applies CORS headers
  3. Path Extraction: Extracts the first path segment for routing lookup
  4. Service Resolution: Maps the path to a configured service instance
  5. Authentication Setup: Adds service-to-service authentication headers
  6. Request Forwarding: Proxies the request to the target service
  7. 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