Documentation Index
Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Modules to Traffic Policy Actions reference
| Endpoint Module | Traffic Policy Action | Phase | Notes |
|---|
oauth | set-vars, oauth, custom-response | on_http_request | Maps OAuth provider and settings. |
oidc | oidc | on_http_request | Maps OpenID Connect settings. |
ip_policy | restrict-ips | on_tcp_connect | Maps allowed IPs or policies. |
mutual_tls and tls_termination | terminate-tls | on_tcp_connect | Maps mTLS and TLS termination settings. |
request_headers | add-headers, remove-headers | on_http_request | Modify request headers. |
response_headers | add-headers, remove-headers | on_http_response | Modify response headers. |
compression | compress-response | on_http_response | Enable response compression. |
webhook_validation | verify-webhook | on_http_request | Validate webhook secrets. |
circuit_breaker | circuit-breaker | on_http_request | Define circuit breaking thresholds. |
saml | (⚠️ Not supported) | N/A | Try OIDC or contact support for help. |
Migration instructions per module
OAuth authentication (oauth)
Old config example:
{
"oauth": {
"provider": "google",
"client_id": "abc",
"client_secret": "def",
"scopes": ["email"],
"email_addresses": ["user@domain.com"],
"email_domains": ["example.com"],
"options_passthrough": true
}
}
on_http_request:
# Setup list of allowed emails and domains
- actions:
- type: set-vars
config:
vars:
- allowed_emails:
- user@example.com
- allowed_email_domains:
- "example.com"
# Run OAuth action for authentication
- actions:
- type: oauth
config:
provider: google
client_id: abc
client_secret: def
scopes:
- email
allow_cors_preflight: true
# Get the result variables and do identity checks
- actions:
- type: set-vars
config:
vars:
# Set the authenticated user to vars.identity
- identity: "${actions.ngrok.oauth.identity}"
# Check whether the email is in the list of allowed emails
- is_email_allowed: "${vars.allowed_emails && !(vars.identity.email in vars.allowed_emails)}"
# Check whether the email domain is in the list of allowed email domains
- is_email_domain_allowed: "${vars.allowed_email_domains && !vars.allowed_email_domains.exists_one(i, (vars.identity.email.endsWith('@' + i))}"
# Check whether the email was allowed or the domain was allowed
# Feel free to customize this to your liking!
- expressions:
- "vars.is_email_allowed || vars.is_email_domain_allowed"
actions:
- type: custom-response
config:
status_code: 403
OpenID Connect authentication (oidc)
Old config example:
{
"oidc": {
"issuer": "https://example.com",
"client_id": "abc",
"client_secret": "def",
"scopes": ["openid", "email"],
"options_passthrough": false,
"cookie_prefix": "auth.example.com",
"maximum_duration": 3600,
"inactivity_timeout": 600,
"auth_check_interval": 300
}
}
on_http_request:
- actions:
- type: oidc
config:
issuer_url: https://example.com
client_id: abc
client_secret: def
scopes:
- openid
- email
allow_cors_preflight: false
auth_cookie_domain: auth.example.com
max_session_duration: "3600s"
idle_session_duration: "600s"
userinfo_refresh_interval: "300s"
IP policy (ip_policy)
Old config example:
{
"ip_policy": {
"ip_policies": [
{ "id": "ipp_123", "uri": "..." }
]
}
}
on_tcp_connect:
- actions:
- type: restrict-ips
config:
ip_policies:
- ipp_123
Mutual TLS and TLS termination (mutual_tls, tls_termination)
Old config example:
{
"mutual_tls": {
"enabled": true,
"certificate_authorities": [{ "id": "ca_abc" }]
},
"tls_termination": {
"enabled": true,
"terminate_at": "edge",
"min_version": "1.3"
}
}
on_tcp_connect:
- actions:
- type: terminate-tls
config:
mutual_tls_certificate_authorities:
- ca_abc
min_version: "1.3"
{
"request_headers": {
"add": {
"X-Test": "123"
},
"remove": ["X-Remove-Me"]
}
}
on_http_request:
- actions:
- type: add-headers
config:
headers:
X-Test: "123"
- actions:
- type: remove-headers
config:
headers:
- X-Remove-Me
{
"response_headers": {
"add": {
"X-Test": "123"
},
"remove": ["X-Remove-Me"]
}
}
on_http_response:
- actions:
- type: add-headers
config:
headers:
X-Test: "123"
- actions:
- type: remove-headers
config:
headers:
- X-Remove-Me
Compression (compression)
Old config example:
{
"compression": {
"enabled": true
}
}
on_http_response:
- actions:
- type: compress-response
Webhook validation (webhook_validation)
Old config example:
{
"webhook_validation": {
"provider": "slack",
"secret": "abcdef"
}
}
on_http_request:
- actions:
- type: verify-webhook
config:
provider: slack
secret: abcdef
Circuit breaker (circuit_breaker)
Old config example:
{
"circuit_breaker": {
"tripped_duration": 30,
"rolling_window": 60,
"num_buckets": 10,
"volume_threshold": 100,
"error_threshold_percentage": 0.5
}
}
on_http_request:
- actions:
- type: circuit-breaker
config:
tripped_duration: "30s"
rolling_window: "60s"
num_buckets: 10
volume_threshold: 100
error_threshold_percentage: 0.5
SAML authentication (saml)
- Traffic Policy does not currently natively support SAML.
- You may want to try out the OIDC action or reach out to ngrok support.
✅ Quick checklist
| Module | Traffic Policy Action |
|---|
| OAuth | set-vars, oauth, custom-response |
| OIDC | oidc |
| IP Policy | ip-restriction |
| Mutual TLS / TLS Term | terminate-tls |
| Request Headers | add-headers, remove-headers |
| Response Headers | add-headers, remove-headers |
| Compression | compress-response |
| Webhook Verification | verify-webhook |
| Circuit Breaker | circuit-breaker |
| SAML | ⚠️ (Not yet supported) |
🛡️ Final Tips
- Always test your Traffic Policy in staging before production.
- Validate YAML syntax carefully—indentation matters.
- If you have complex
expressions, validate them in small steps.
- If unsure, rebuild small features first, then layer on more complex features.
- Backup your endpoint configuration before deletion.
