Network Proxy Configuration

Katalogue has two distinct proxy-related configuration areas that are easy to confuse because they solve opposite problems:

	Reverse proxy	Egress proxy
Direction	Inbound — traffic coming in to Katalogue	Outbound — traffic going out from Katalogue
What it is	A load balancer or reverse proxy in front of Katalogue (e.g. nginx, Traefik)	A corporate HTTP proxy that all outbound internet traffic must pass through
What breaks without it	Client IPs appear as the proxy IP; req.secure is wrong; rate limiting and cookie security behave incorrectly	Calls to Microsoft Graph, Azure token endpoints, OIDC discovery, and remote file fetches fail
Config parameter(s)	TRUST_PROXY	HTTPS_PROXY, HTTP_PROXY, NO_PROXY

---

Reverse Proxy

When Katalogue is hosted behind a reverse proxy or load balancer, the proxy forwards requests on behalf of clients and attaches the original client IP in an X-Forwarded-For header. Set TRUST_PROXY to tell Katalogue to trust these forwarded headers.

Caution

Setting TRUST_PROXY to true trusts all X-Forwarded-For headers unconditionally. In production, set it to your specific upstream proxy IP or CIDR range (e.g. 10.0.0.1 or 10.0.0.0/24) so that clients cannot spoof their IP and bypass rate limiting on login endpoints.

{
  "config": {
    "TRUST_PROXY": "10.0.0.1"
  }
}

See TRUST_PROXY in the Config Parameter Reference for accepted values.

Path Routing Rules

The api service exposes its endpoints under a few distinct path families. A reverse proxy in front of Katalogue must forward each of them to the api backend. The paths are configurable, so route them by the config value (defaults shown in parentheses):

Path prefix	Config parameter	Default	Purpose
<API_ENDPOINT_PATH>/*	API_ENDPOINT_PATH	/api/*	REST API and GUI resource endpoints
<REST_API_OIDC_PATH>/*	REST_API_OIDC_PATH	/oidc/*	OIDC provider (token, JWKS, discovery)
<REST_API_DOCS_PATH>/*	REST_API_DOCS_PATH	/docs/*	Interactive API documentation (Redoc + OpenAPI spec)
/health	—	/health	Health check (fixed, not configurable)

All four forward to the same api service origin. With the default configuration, that is four routing rules: /api/*, /oidc/*, /docs/*, and /health.

Note

The OIDC provider and API docs are served at their own root-level paths, not nested under API_ENDPOINT_PATH. The OIDC issuer is therefore <API_ENDPOINT_BASE_URL><REST_API_OIDC_PATH> (e.g. https://katalogue.example.com/oidc), and the token endpoint is at <issuer>/token.

---

Corporate Egress Proxy

In corporate environments, outbound internet traffic is often required to pass through a central HTTP proxy. Katalogue makes several outbound HTTPS calls that need to be routed through this proxy:

• Microsoft Graph API (user and group synchronisation, email via Graph)
• Azure Active Directory token and JWKS endpoints (OIDC authentication)
• Azure Key Vault (connection password retrieval)
• Remote file fetches (e.g. dbt manifest URLs)

Set HTTPS_PROXY (and optionally HTTP_PROXY) to the URL of your corporate proxy server.

{
  "config": {
    "proxy": {
      "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
      "HTTP_PROXY": "http://proxy.corp.example.com:8080",
      "NO_PROXY": "internal.corp.example.com,10.0.0.0/8"
    }
  }
}

Note

Katalogue automatically adds its own hostname (from API_ENDPOINT_BASE_URL) to NO_PROXY at startup, so internal OIDC token verification calls are never routed through the proxy.

What is not proxied

• SMTP email — SMTP connections are TCP-level and are not affected by HTTPS_PROXY. If your SMTP server requires proxy access, configure network routing at the infrastructure level.
• Database connections — PostgreSQL connections bypass the proxy regardless of these settings.