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