Skip to main content
If you’re behind a load balancer or reverse proxy, you MUST configure trusted proxies or rate limiting will break — all traffic will appear to come from a single IP (the proxy’s), triggering limits for your entire deployment at once.

Quick Setup

  1. Go to Settings > Network > Trusted Proxies.
  2. Paste your load balancer’s internal IP or CIDR range.
  3. Save.
If you’re using AWS ALB:
(ALB forwards from within your VPC’s private range.) If you’re using nginx on the same host:
If you’re using Cloudflare: Add Cloudflare’s published IP ranges (see https://www.cloudflare.com/ips/):
If you’re using a Kubernetes service mesh (Envoy/Istio):

Verify it works

After saving, check that Observal resolves the correct client IP:
Expected: Your actual public IP (not the proxy’s IP). If you see the proxy’s IP instead, the trusted proxy list doesn’t include your proxy’s address. Also check the audit log: Settings > Audit Log should show distinct IPs for different users, not a single proxy IP for everyone.

Field Reference

Trusted Proxy IPs

A list of IP addresses or CIDR ranges that Observal trusts to set forwarding headers (X-Forwarded-For, X-Real-IP, X-Forwarded-Proto). Affects: IP resolution for rate limiting, audit logs, and access controls. Only IPs in this list are trusted to pass X-Forwarded-For. Traffic from unlisted IPs uses the TCP source address directly, ignoring forwarding headers. Default: 172.16.0.0/12, 10.0.0.0/8, 192.168.0.0/16, 127.0.0.1 (private networks and localhost) Format: Comma-separated IPs or CIDR blocks. Values: When to set: When deploying behind any load balancer, reverse proxy, or CDN. Without correct configuration, all users appear as the proxy’s IP in audit logs and share one rate-limit bucket. Security best practice: Never add 0.0.0.0/0 (trust everything). This allows any client to spoof their apparent IP address. Symptom-to-fix:

SSRF Protection

Server-Side Request Forgery (SSRF) protection prevents Observal from making outbound requests to internal/private networks when processing user-supplied URLs (webhook destinations, IdP metadata URLs, custom API base URLs). Settings: Default blocked ranges:
  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
  • 169.254.0.0/16 (link-local / cloud metadata)
  • 127.0.0.0/8 (loopback)
  • ::1/128, fc00::/7, fe80::/10 (IPv6 equivalents)
When to add allow-listed hosts:
  • Your IdP metadata URL is on an internal hostname (e.g., idp.internal.yourcompany.com).
  • Webhooks need to reach an internal service (e.g., slack-gateway.internal:8080).
Warning: Never disable SSRF protection in production. Use the allow-list for legitimate internal targets.
Symptom-to-fix:

Allow Internal Git URLs

Whether agent and component definitions can reference Git repositories on private/internal networks. Affects: Agent scaffolding and component installation from Git sources. When false, Git URLs that resolve to private IP ranges (RFC 1918) are blocked by SSRF protection. When true, internal Git repos are permitted. Values: When to set: Your deployment hosts agent source code on an internal GitLab/Gitea/GitHub Enterprise instance that resolves to a private IP. Enable this so observal publish and component installs can clone from internal repos.