secure-endpoint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Secure an endpoint

保护 endpoint

Add access control, throttling, or an edge response to an endpoint with a Traffic Policy - no app changes. One skill covers the common gates; jump to the scenario that matches the ask.

使用 Traffic Policy 为 endpoint 添加访问控制、流量节流或边缘响应——无需更改应用。选择与需求匹配的场景即可；一个 skill 涵盖常见的访问关卡。

Before you start

开始之前

Auth is required (

ngrok-setup

). Pull action configs and, if the endpoint being secured is a private receiver, the internal-binding rules from

ngrok-engine

身份验证是必需的（

ngrok-setup

）。从

ngrok-engine

获取 action 配置；如果要保护的 endpoint 是私有 receiver，还需获取内部绑定规则。

Scenarios

使用场景

Require login (OAuth / OIDC)

要求登录（OAuth / OIDC）

Gate the endpoint behind an identity provider, then optionally restrict to specific users.

yaml

on_http_request:
  - actions:
      - type: oauth
        config: { provider: google }
  - expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('@yourcompany.com')"
    actions:
      - type: deny

Full provider list and raw OIDC:

ngrok-engine

ngrok-engine/references/auth-actions.md

将 endpoint 置于身份提供商之后，然后可以选择将访问限制为特定用户。

yaml

on_http_request:
  - actions:
      - type: oauth
        config: { provider: google }
  - expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('@yourcompany.com')"
    actions:
      - type: deny

完整的提供商列表和原始 OIDC 配置：

ngrok-engine

ngrok-engine/references/auth-actions.md

。

Lock to specific IPs

锁定特定 IP

Allow only known addresses/CIDRs; deny the rest.

yaml

on_http_request:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 203.0.113.4/32
            - 198.51.100.0/24

Use

restrict-ips

for ranges.

conn.client_ip in [...]

does exact string comparison: it matches a bare address (

'203.0.113.4'

) but never a CIDR, because

203.0.113.4

is not equal to the string

203.0.113.4/32

- so a list of CIDRs matches nothing and the rule denies everyone.

restrict-ips

is what evaluates CIDRs. A CEL

in

test is fine for a couple of exact addresses.

仅允许已知地址/CIDR；拒绝其余请求。

yaml

on_http_request:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 203.0.113.4/32
            - 198.51.100.0/24

对于地址范围，请使用

restrict-ips

。

conn.client_ip in [...]

执行精确的字符串比较：它可以匹配不带掩码的地址（

'203.0.113.4'

），但永远不会匹配 CIDR，因为

203.0.113.4

不等于字符串

203.0.113.4/32

，因此 CIDR 列表不会匹配任何内容，最终会拒绝所有请求。只有

restrict-ips

才能计算 CIDR。对于少量精确地址，可以使用 CEL

in

测试。

Block a path or condition (deny)

阻止某个 path 或条件（deny）

yaml

on_http_request:
  - expressions: ["req.url.path.startsWith('/admin')"]
    actions:
      - type: deny
        config: { status_code: 403 }

yaml

on_http_request:
  - expressions: ["req.url.path.startsWith('/admin')"]
    actions:
      - type: deny
        config: { status_code: 403 }

Rate limit

速率限制

Throttle by client to protect the upstream. Get the current

rate-limit

action config from

ngrok-engine

(it takes a name, rate, bucket key, algorithm, and capacity) and attach it the same way as the others.

按客户端进行限流，以保护上游服务。从

ngrok-engine

获取当前的

rate-limit

action 配置（它需要 name、rate、bucket key、algorithm 和 capacity 参数），并以与其他 action 相同的方式附加。

Maintenance page / custom response

维护页面 / 自定义响应

Return a response straight from the edge without hitting the upstream.

yaml

on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 503
          headers: { content-type: text/html }
          body: "<html><body><h1>Back soon</h1></body></html>"

Health check that never touches the app:

yaml

on_http_request:
  - expressions: ["req.url.path == '/healthz'"]
    actions:
      - type: custom-response
        config:
          {
            status_code: 200,
            headers: { content-type: text/plain },
            body: "ok",
          }

直接从边缘返回响应，而不访问上游服务。

yaml

on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 503
          headers: { content-type: text/html }
          body: "<html><body><h1>Back soon</h1></body></html>"

完全不接触应用的健康检查：

yaml

on_http_request:
  - expressions: ["req.url.path == '/healthz'"]
    actions:
      - type: custom-response
        config:
          {
            status_code: 200,
            headers: { content-type: text/plain }
            body: "ok",
          }

Add / strip headers

添加 / 移除标头

Usually a supporting step (inject an upstream auth header, add CORS, remove a header). See

add-headers

ngrok-engine

这通常是辅助步骤（注入上游 auth 标头、添加 CORS、移除标头）。有关详情，请参阅

ngrok-engine

中的

add-headers

。

Combining

组合规则

Rules run in order; stack them. Typical API-gateway front door: restrict-ips -> oauth -> rate-limit -> forward. Keep terminating actions (

deny

custom-response

) in the rule that should stop the chain.

规则按顺序运行，可以叠加使用。典型的 API gateway 入口层：restrict-ips -> oauth -> rate-limit -> forward。请将终止型 action（

deny

、

custom-response

）放在应当停止处理链的规则中。

Apply it

应用

Attach the policy on the user's surface - see

ngrok-surfaces

. Same policy body everywhere. If the ngrok MCP server is connected, validate the policy first (see

ngrok-engine

将 policy 附加到用户的 surface 上——参见

ngrok-surfaces

。所有位置使用相同的 policy 正文。如果已连接 ngrok MCP server，请先验证 policy（参见

ngrok-engine

）。

Notes for agents

给 Agent 的说明

Match the scenario to the user's words; don't dump all of them.
These compose with other jobs: securing a webhook receiver is this skill's auth rules plus
```
receive-webhooks
```
' verify+forward.
No app code changes - if you're reaching for the app's auth middleware, stop; that's what this replaces.

根据用户的表述选择对应场景；不要一次性列出所有场景。
这些规则可以与其他任务组合：保护 webhook receiver 时，需要应用本 skill 的 auth 规则以及
```
receive-webhooks
```
的 verify+forward。
无需更改应用代码——如果准备使用应用的 auth middleware，请停止；这正是本 skill 要替代的方案。