Gateway Configuration Reference

This reference documents the configuration options for the gateway service.

Core Configuration

This section documents the complete configuration provided by Vidos.

{
    "cors": {
        "enabled": false,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
        "exposeHeaders": [],
        "allowHeaders": [],
        "maxAge": 86400
    },
    "paths": {}
}

Configuration Schema

The complete JSON Schema for the gateway configuration is available:

Download gateway.schema.json

Configuration Options

cors Configuration

For CORS configuration options see the CORS Configuration Reference.

paths Configuration

The paths object defines mappings from URL paths to destination services. Each key in the object represents a path segment that will be routed to a specific service instance.

Type: object (record of path keys to destination objects)
Default: {}
Description: Maps incoming request paths to service destinations
Constraints:
- Path keys must only contain alphanumeric characters, hyphens, and underscores ([-_a-zA-Z0-9])
- Each path maps to a gateway destination object
Effects:
- Controls routing of incoming requests
- Determines service integration points
- Configures service-to-service authentication

Gateway Destination

Each value in the paths object is a gateway destination object:

Type: object
Properties:
- type: "instance" (reference to a specific instance)
- service: string (one of "authorizer", "resolver", "verifier", or "validator")
- resourceId: string (resource ID of the target service instance)
- serviceRole: Service role reference object
Description: Specifies which service instance handles requests for a path

Example configuration with paths:

{
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "my-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-role"
            }
        },
        "resolve": {
            "type": "instance",
            "service": "resolver",
            "resourceId": "my-resolver",
            "serviceRole": {
                "owner": "managed",
                "resourceId": "resolver_all_actions"
            }
        }
    }
}

service

Type: string (enum)
Allowed values:
- "authorizer": Routes requests to an authorizer service
- "resolver": Routes requests to a resolver service
- "verifier": Routes requests to a verifier service
- "validator": Routes requests to a validator service
Description: Specifies which type of service the request will be forwarded to

serviceRole

Controls the authentication used when forwarding requests to the service.

Type: object
Properties:
- owner: string (one of "account" or "managed")
- resourceId: string (resource ID of the service role)
Description: Service role reference for authentication
See: Service Roles Reference

Example account-owned role:

{
    "serviceRole": {
        "owner": "account",
        "resourceId": "my-custom-role"
    }
}

Example managed role:

{
    "serviceRole": {
        "owner": "managed",
        "resourceId": "service_role_id"
    }
}

Request Forwarding

When a request is received at the Gateway, it's processed as follows:

The first path segment is extracted from the request URL
The Gateway looks up this segment in the paths configuration
If a matching path is found, the request is forwarded to the configured service instance
The request is forwarded with additional headers for service-to-service authentication
The remaining path segments are preserved in the forwarded request

For example, with the following configuration:

{
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "main-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-role"
            }
        }
    }
}

A request to /auth/token would be forwarded to the authorizer instance with path /token. The gateway will add authentication headers for service-to-service communication.

Configuration Scenarios

Basic Gateway with Authorizer and Resolver

This example configures a gateway with paths for both an authorizer and a resolver service:

{
    "cors": {
        "enabled": true,
        "origin": ["https://example.com"],
        "credentials": true,
        "allowMethods": ["GET", "POST", "OPTIONS"],
        "allowHeaders": ["Content-Type", "Authorization"],
        "exposeHeaders": [],
        "maxAge": 86400
    },
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "main-authorizer",
            "serviceRole": {
                "owner": "managed",
                "resourceId": "authorizer_all_actions"
            }
        },
        "resolve": {
            "type": "instance",
            "service": "resolver",
            "resourceId": "main-resolver",
            "serviceRole": {
                "owner": "account",
                "resourceId": "resolver-service-role"
            }
        }
    }
}

Verification API Gateway

This example configures a gateway with paths for both verifier and validator services:

{
    "cors": {
        "enabled": true,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST"],
        "allowHeaders": ["Content-Type"],
        "exposeHeaders": [],
        "maxAge": 3600
    },
    "paths": {
        "verify": {
            "type": "instance",
            "service": "verifier",
            "resourceId": "main-verifier",
            "serviceRole": {
                "owner": "account",
                "resourceId": "verifier-role"
            }
        },
        "validate": {
            "type": "instance",
            "service": "validator",
            "resourceId": "main-validator",
            "serviceRole": {
                "owner": "account",
                "resourceId": "validator-role"
            }
        }
    }
}

Multiple Authorizer Instances

This example routes different authentication methods to separate authorizer instances:

{
    "paths": {
        "login": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "login-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-admin-role"
            }
        },
        "mdl": {
            "service": "authorizer",
            "resourceId": "mdl-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-admin-role"
            }
        }
    }
}

Additional Resources

ON THIS PAGE

#Gateway Configuration Reference

#Core Configuration

#Configuration Schema

#Configuration Options

#cors Configuration

#paths Configuration

#Gateway Destination

#service

#serviceRole

#Request Forwarding

#Configuration Scenarios

#Basic Gateway with Authorizer and Resolver

#Verification API Gateway

#Multiple Authorizer Instances

#Additional Resources