Migrate from Modules to Traffic Policy Actions - ngrok documentation

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
  }
}

New Traffic Policy YAML: Leverages the following actions:

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
  }
}

New Traffic Policy YAML: Leverages the following actions:

oidc

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": "..." }
    ]
  }
}

New Traffic Policy YAML: Leverages the following actions:

restrict-ips

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"
  }
}

New Traffic Policy YAML: Leverages the following actions:

terminate-tls

on_tcp_connect:
  - actions:
    - type: terminate-tls
      config:
        mutual_tls_certificate_authorities:
          - ca_abc
        min_version: "1.3"

Request headers (`request_headers`)

Old config example:

{
  "request_headers": {
    "add": {
      "X-Test": "123"
    },
    "remove": ["X-Remove-Me"]
  }
}

New Traffic Policy YAML: Leverages the following actions:

on_http_request:
  - actions:
    - type: add-headers
      config:
        headers:
          X-Test: "123"
  - actions:
    - type: remove-headers
      config:
        headers:
          - X-Remove-Me

Response headers (`response_headers`)

Old config example:

{
  "response_headers": {
    "add": {
      "X-Test": "123"
    },
    "remove": ["X-Remove-Me"]
  }
}

New Traffic Policy YAML: Leverages the following actions:

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
  }
}

New Traffic Policy YAML: Leverages the following actions:

compress-response

on_http_response:
  - actions:
    - type: compress-response

Webhook validation (`webhook_validation`)

Old config example:

{
  "webhook_validation": {
    "provider": "slack",
    "secret": "abcdef"
  }
}

New Traffic Policy YAML: Leverages the following actions:

verify-webhook

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
  }
}

New Traffic Policy YAML: Leverages the following actions:

circuit-breaker

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.