全部产品
Search
文档中心

API 网关:IP访问控制插件

更新时间:Nov 14, 2024

IP访问控制插件API网关提供的 API 安全防护组件之一,负责控制 API 的调用来源 IP (支持IP段)。您可以通过配置某个 API 的 IP 白名单/黑名单来允许/拒绝某个来源的API请求。

1. 概述

支持白名单或黑名单方式:

  • 白名单:支持配置 IP 或者 APPID + IP 的白名单访问,不在白名单列表的请求将会被拒绝。 

    • IP 白名单,只允许设定的调用来源 IP 的请求被允许。

    • APPID + IP 此APPID只能在设定的 IP 下访问,其他 IP 来源将被拒绝。

  • 黑名单:您可以配置 IP 黑名单,黑名单中 IP 的访问将被 API 网关拒绝。

重要

IP访问控制插件仅支持IPv4地址,不支持IPv6地址。

2. 插件配置

可以选择JSON或者YAML格式的来配置您的插件,两种格式的schema相同,可以搜索yaml to json转换工具来进行配置格式的转换,yaml格式的模板见下表。

---
type: ALLOW           # 控制模式,支持白名单模式'ALLOW'和黑名单模式'REFUSE'
resource: "XFF:-1"   # 可选字段,如果设置本字段,取X-Forwarded-For头中的IP作为判断依据,本示例取XFF头的倒数第一个IP作为客户端源IP判断,
items: 
- blocks:         # IP地址段
  - 61.3.XX.XX/24   # 使用CIDR方式配置
  appId: 219810   # (可选)如果配置了appId则该条目仅对该AppId生效
- blocks:         # IP地址
  - 79.11.XX.XX    # 使用IP地址方式配置
- blocks:         # 用户VPC
  - 192.168.XX.XX/32    # 专享实例场景,从用户VPC内访问API网关的请求,API网关看到的来源地址处于这个地址段

需要特别注意最后一点,专享实例场景,API网关允许从用户VPC内发送请求到API网关,此时API网关可以直接读取来源VPC内的地址,比如192.168.XX.XX,用户设置黑白名单时可以直接使用VPC内地址作为配置值。

3. 穿透WAF配置

如果API网关前面有WAF等中间件,业务需要实现API级别IP黑白名单能力时,就需要用到resource字段,resource字段为可选字段,如果不填写,取和网关直接连接前一跳的IP作为判断依据。如果填写本字段,允许设置X-Forwarded-For头中的值作为IP判断依据。

说明

WAF会将它收到的请求的源IP加入到X-Forwarded-For头的最后发送给API网关,API网关去判断X-Forwarded-For头中的这个值就可以。这种情况建议用户使用"XFF:-1"来判断WAF前一跳的IP地址。

resource字段填写格式为“XFF:index”,index的值为X-Forwarded-For头中IP排序序号,从0开始算,允许负数,比如X-Forwarded-For的值为IP1,IP2,IP3,那么如果index值为0,取IP1,如果index的值为-1,取IP3,也就是倒数第一个IP。

4. 跨VPC访问

在跨VPC访问的情况,API网关可以直接从请求中读取来源VPC内的IP地址,您可以放心编写针对VPC内IP的IP访问控制插件。API网关还可以读取到来源VPC的VPCID,您可以通过设置参数访问控制插件来设置只允许某些指定的VPC访问您的API。

5. 接入WAF的同时跨VPC访问

有一种场景,用户的API需要同时对公网和内网提供服务,而在公网提供服务的时候,在API网关前接入了WAF中间件,需要API网关对WAF前的客户端做IP访问控制,同时需要对内网来源做IP访问控制。网关为了这种场景做了适配,用户可以用resource字段和allowResourceMissing字段配合使用来实现同时控制内网和使用WAF等中间件的公网的来源IP。用户通过设置resource字段来指定API网关从X-Forwarded-For头中获取透过WAF中间件过来的客户端的IP,通过allowResourceMissing字段来配置API网关遇到客户端没有传X-Forwarded-For头时的内网访问场景,从前一跳获取客户端的IP作为判断依据。下面是例子:

---
type: ALLOW           # 控制模式,支持白名单模式'ALLOW'和黑名单模式'REFUSE'
resource: "XFF:-1"   # 可选字段,如果设置本字段,取X-Forwarded-For头中的IP作为判断依据,本示例取XFF头的倒数第一个IP作为客户端源IP判断
allowResourceMissing: "true"  #允许Resource缺失,缺失时取API网关的前一跳的IP作为判断条件
items: 
- blocks:         # IP地址段
  - 61.3.XX.XX/24   # 使用CIDR方式配置
  appId: 219810   # (可选)如果配置了appId则该条目仅对该AppId生效
- blocks:         # IP地址
  - 79.11.XX.XX    # 使用IP地址方式配置
- blocks:         # 用户VPC
  - 192.168.XX.XX/32    # 专享实例场景,从用户VPC内访问API网关的请求,API网关看到的来源地址处于这个地址段

6. IP访问控制插件支持插件数据集

IP访问控制插件的配置和详细说明参考IP访问控制插件

6.1. 创建插件数据集

  1. 登录API网关控制台,选择地域并在左侧导航栏选择API管理 > 插件管理

  2. 插件列表页面选择自定义数据集栏,单击页面右上角创建数据集,在创建数据集弹框中填写数据集的名称类型选择IP_WHITELIST_CIDR

    image

  3. 单击目标数据集ID,进入数据集页面单击创建数据集条目,在创建数据集条目弹框中填写数据值(IP地址或IP地址段)和过期时间(数据集中的数据条目在到达其过期时间后将自动失效。)。

    image

重要

插件数据集只在专享实例生效,如果您配置了数据集的插件所绑定的API不是配置在专享实例上,那么插件中配置的数据集将不生效。

6.2. IP访问控制插件配置插件数据集

IP访问控制插件中配置插件数据集是在IP访问控制插件中配置的基础上,在items集合元素中增加blocksDatasetId字段,该字段的值就是上述创建的IP_ACCESS_CIDR类型的数据集ID。blocksDatasetIdblocks是相互兼容的,每个item中可以同时配置blocksDatasetIdblocks,也可以单独配置其中一个。

---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3
  blocks:
  - 127.0.XX.XX
  - 192.168.XX.XX/24