> ## 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.

# Migrate from Modules to Traffic Policy Actions

> Reference guide for migrating from deprecated Edge modules to Traffic Policy actions including mapping tables and migration examples.

## Modules to Traffic Policy Actions reference

| Endpoint Module | Traffic Policy Action | Phase | Notes |
| - | - | - | - |
| `oauth` | [`set-vars`](/docs/gateway/traffic-policy/actions/set-vars/), [`oauth`](/docs/gateway/traffic-policy/actions/oauth), [`custom-response`](/docs/gateway/traffic-policy/actions/custom-response) | [`on_http_request`](/docs/gateway/traffic-policy/how-it-works#phases) | Maps OAuth provider and settings. |
| `oidc` | [`oidc`](/docs/gateway/traffic-policy/actions/oidc) | [`on_http_request`](/docs/gateway/traffic-policy/how-it-works#phases) | Maps OpenID Connect settings. |
| `ip_policy` | [`restrict-ips`](/docs/gateway/traffic-policy/actions/restrict-ips) | [`on_tcp_connect`](/docs/gateway/traffic-policy/how-it-works#phases) | Maps allowed IPs or policies. |
| `mutual_tls` and `tls_termination` | [`terminate-tls`](/docs/gateway/traffic-policy/actions/terminate-tls) | [`on_tcp_connect`](/docs/gateway/traffic-policy/how-it-works#phases) | Maps mTLS and TLS termination settings. |
| `request_headers` | [`add-headers`](/docs/gateway/traffic-policy/actions/add-headers), [`remove-headers`](/docs/gateway/traffic-policy/actions/remove-headers) | [`on_http_request`](/docs/gateway/traffic-policy/how-it-works#phases) | Modify request headers. |
| `response_headers` | [`add-headers`](/docs/gateway/traffic-policy/actions/add-headers), [`remove-headers`](/docs/gateway/traffic-policy/actions/remove-headers) | [`on_http_response`](/docs/gateway/traffic-policy/how-it-works#phases) | Modify response headers. |
| `compression` | [`compress-response`](/docs/gateway/traffic-policy/actions/compress-response) | [`on_http_response`](/docs/gateway/traffic-policy/how-it-works#phases) | Enable response compression. |
| `webhook_validation` | [`verify-webhook`](/docs/gateway/traffic-policy/actions/verify-webhook) | [`on_http_request`](/docs/gateway/traffic-policy/how-it-works#phases) | Validate webhook secrets. |
| `circuit_breaker` | [`circuit-breaker`](/docs/gateway/traffic-policy/actions/circuit-breaker) | [`on_http_request`](/docs/gateway/traffic-policy/how-it-works#phases) | 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:**

```json theme={null}
{
  "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:

* [`set-vars`](/docs/gateway/traffic-policy/actions/set-vars)
* [`oauth`](/docs/gateway/traffic-policy/actions/oauth)
* [`custom-response`](/docs/gateway/traffic-policy/actions/custom-response)

```yaml theme={null}
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:**

```json theme={null}
{
  "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`](/docs/gateway/traffic-policy/actions/oidc)

```yaml theme={null}
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:**

```json theme={null}
{
  "ip_policy": {
    "ip_policies": [
      { "id": "ipp_123", "uri": "..." }
    ]
  }
}
```

**New Traffic Policy YAML:**

Leverages the following actions:

* [`restrict-ips`](/docs/gateway/traffic-policy/actions/restrict-ips)

```yaml theme={null}
on_tcp_connect:
  - actions:
    - type: restrict-ips
      config:
        ip_policies:
          - ipp_123
```

### Mutual TLS and TLS termination (`mutual_tls`, `tls_termination`)

**Old config example:**

```json theme={null}
{
  "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`](/docs/gateway/traffic-policy/actions/terminate-tls)

```yaml theme={null}
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:**

```json theme={null}
{
  "request_headers": {
    "add": {
      "X-Test": "123"
    },
    "remove": ["X-Remove-Me"]
  }
}
```

**New Traffic Policy YAML:**

Leverages the following actions:

* [`add-headers`](/docs/gateway/traffic-policy/actions/add-headers)
* [`remove-headers`](/docs/gateway/traffic-policy/actions/remove-headers)

```yaml theme={null}
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:**

```json theme={null}
{
  "response_headers": {
    "add": {
      "X-Test": "123"
    },
    "remove": ["X-Remove-Me"]
  }
}
```

**New Traffic Policy YAML:**

Leverages the following actions:

* [`add-headers`](/docs/gateway/traffic-policy/actions/add-headers)
* [`remove-headers`](/docs/gateway/traffic-policy/actions/remove-headers)

```yaml theme={null}
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:**

```json theme={null}
{
  "compression": {
    "enabled": true
  }
}

```

**New Traffic Policy YAML:**

Leverages the following actions:

* [`compress-response`](/docs/gateway/traffic-policy/actions/compress-response)

```yaml theme={null}
on_http_response:
  - actions:
    - type: compress-response
```

### Webhook validation (`webhook_validation`)

**Old config example:**

```json theme={null}
{
  "webhook_validation": {
    "provider": "slack",
    "secret": "abcdef"
  }
}
```

**New Traffic Policy YAML:**

Leverages the following actions:

* [`verify-webhook`](/docs/gateway/traffic-policy/actions/verify-webhook)

```yaml theme={null}
on_http_request:
  - actions:
    - type: verify-webhook
      config:
        provider: slack
        secret: abcdef
```

### Circuit breaker (`circuit_breaker`)

**Old config example:**

```json theme={null}
{
  "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`](/docs/gateway/traffic-policy/actions/circuit-breaker)

```yaml theme={null}
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](/docs/gateway/traffic-policy/actions/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.