开放平台 IP 白名单接入指南

前言

为提高商户访问开放平台的安全性,避免商户因应用私钥泄漏等原因导致业务受损,开放平台提供 IP 白名单机制,基于该机制商户可以给 资金操作类敏感接口 配置 IP 白名单,开放平台将基于商户配置的 IP 白名单,校验商户请求的来源 IP,若来源 IP 不在配置的 IP 白名单范围内,开放平台将拦截掉对应请求。


注:要配置的IP为开发者服务器的出口IP,请在配置前一定要仔细检查要配置的 IP(列表)正确性、完整性,


配置方式

以网页&移动应用配置为例,开发者通过开发者中心 > 网页&移动应用 > 应用信息 > IP白名单 > 设置/查看,进入 IP 白名单管理页面。

image.png


在 IP 白名单管理页面中,可以增加新的 IP 白名单,也可以修改、删除、查询当前已存在的IP白名单。

image.png


当前开放平台提供两种 IP 白名单配置方式,配置部分接口 IP 白名单配置全量接口接口 IP 白名单,下面分别介绍两种 IP 白名单的配置方式。


配置部分接口 IP 白名单

该场景主要是针对开放平台提供的 资金操作类敏感接口 配置 IP 白名单,若商户需要对这些接口做来源 IP 管控,商户可通过 配置部分接口 IP 白名单的方式来设置。 


注:若应用为某接口配置了部分接口 IP 白名单,同时应用也配置了全量接口 IP 白名单,则该接口以配置的部分接口 IP 白名单为准,忽略全量接口 IP 白名单,详见 拦截规则说明


新增 IP 白名单

IP 白名单管理 页面点击 添加规则,在弹框 添加接口 中选择 配置部分接口 ,配置页面将展示 当前应用已签约的高风险接口列表(若应用想配置非高风险接口的 IP 白名单,请选择 配置全量接口 IP 白名单),开发者可根据自身诉求勾选对应的接口并配置 IP 白名单。

image.png


勾选完接口后,点击 下一步 配置具体的 IP 列表,IP 配置规则详见 配置规则说明IP 配置完之后,点击 确认添加,完成 IP 白名单添加。

image.png

修改 IP 白名单

IP 白名单管理 页面,在所需修改的 IP 白名单规则操作列点击 修改,在弹框 修改接口 中重新勾选接口列表并重新配置 IP。

image.png


image.png


image.png

删除 IP 白名单

IP 白名单管理 页面,在所需删除的IP白名单规则操作列点击 删除,执行对应 IP 白名单规则删除。

image.png


配置全量接口 IP 白名单

该类型 IP 白名单主要用于以下场景:


  • 场景1: 开发者希望配置的接口不在 资金操作类敏感接口 中,无法通过 部分接口配置 方式设置 IP 白名单的。
  • 场景2: 开放者希望针对全量接口设置统一的IP白名单。


注:

  1. 全量接口是指商户通过http请求直接访问开放平台openapi网关(访问域名 openapi.alipay.com),且网关正确处理后返回的响应报文是标准Json字符串,而不是返回 302 重定向(页面跳转)的所有接口。
  2. 若应用为某接口配置了部分接口IP白名单,同时应用也配置了全量接口IP白名单,则该接口以配置的部分接口 IP白名单为准,忽略全量接口IP白名单,详见 拦截规则说明


新增 IP 白名单

IP 白名单管理 页面点击 添加规则,在弹框 添加接口 中选择 配置全量接口。

说明:选择 配置全量接口,配置页面中将不会展示详细接口列表。

image.png


image.png


修改 IP 白名单

IP白名单管理 页面,在所需修改的IP白名单规则操作列点击 修改,在弹框 修改接口 中重新勾选接口列表并重新配置 IP 白名单。

image.png


image.png


image.png


删除 IP 白名单

IP白名单管理 页面,在所需删除的IP白名单规则操作列点击 删除,执行对应 IP 白名单规则删除。

image.png


IP 白名单规则说明

IP 白名单配置规则

当前开放平台支持开发者在配置 IP 文本时使用几种格式的 ip:

  • 支持单 ipv4 地址(如123.103.49.137);
  • 支持 ipv4/子网掩码(如123.103.49.137/24);
  • 支持单 ipv6 地址(如2409:8800:8813:208a:617a:6125:d33f:79e0、::79e0);
  • 支持 ipv6/网络位(如2409:8800:8813::/64);
  • 支持以上几种格式 ip 配置的组合。


注:针对多 ip 组合配置,不要将“,”放到 IP 配置的开头或结尾,也不能存在多个连续的“,”,否则保存 IP 配置时会报错。


错误 IP 配置示例:

,123.103.49.16,11.12.12.12  //该配置中,逗号(“,")放到ip的开头,保存时会报错 “第[1]个ip配置[]不合法”
123.103.49.16,11.12.12.12,  //该配置中,逗号(“,”)放到ip配置的结尾,保存时会报错 “第[3]个ip配置[]不合法”
123.103.49.16,,11.12.12.12  //该配置中,存在两个连续的逗号且中间没有任何ip,保存时会报错 “第[2]个ip配置[]不合法”


正确 IP 配置示例:

123.103.49.18,19.215.239.16  //正确配置


IP 白名单拦截规则


当前开放平台支持 配置部分接口配置全量接口 两种方式配置 IP 白名单,针对这两种规则,开放平台校验规则如下:


  • 场景1:若应用仅配置了部分接口 IP 白名单开放平台网关针对该应用的接口请求,会判断该 IP 白名单中是否包含请求中的接口。若包含,开放平台网关则以该 IP 白名单校验请求来源 IP。
  • 场景2:若应用仅配置了全量接口 IP 白名单,开放平台网关针对该应用的所有接口请求,都会使用该 IP 白名单来校验请求来源 IP。

注:全量接口是指商户通过http请求直接访问开放平台openapi网关(访问域名 openapi.alipay.com),且网关正确处理后返回的响应报文是标准Json字符串,而不是返回302重定向(页面跳转)的所有接口。

  • 场景3:若应用配置了部分接口 IP 白名单,同时也配置了全量接口 IP 白名单,开放平台网关针对该应用的接口请求,会先判断部分接口 IP 白名单中是否包含该请求中的接口。若包含,开放平台网关则以命中的部分接口 IP 白名单校验该请求来源 IP,同时忽略全量接口 IP 白名单;若不包含,开放平台网关则以全量接口 IP 白名单校验请求来源 IP。


针对场景3,举例说明,比如应用 A 存在以下4个 IP 白名单配置:

配置1:部分接口IP白名单,接口 alipay.ebpp.pdeduct.pay,ip配置 123.103.49.10
配置2:部分接口IP白名单,接口 alipay.ebpp.pdeduct.pay,alipay.marketing.voucher.send ip配置 123.103.49.11
配置3:部分接口IP白名单,接口 alipay.marketing.cashvoucher.template.create ip配置 123.103.49.12
配置4:全量接口IP白名单,ip配置 123.103.49.13


若应用 A 调用 alipay.ebpp.pdeduct.pay 的请求来源 IP 是 123.103.49.13,开放平台网关收到该请求后,发现该接口存在以部分接口方式配置的 IP 白名单(配置1、配置2),开放平台网关将只使用命中的部分接口 IP 白名单(配置1、配置2)校验来源 IP,校验结果是来源 IP 不在白名单中,尽管该请求的来源 IP 在该应用的全量接口 IP 白名单中(配置4),但开放平台网关依旧会拦截该请求(请求被拦截后网关返回的响应报文示例如下)。

{
    "alipay_marketing_voucher_send_response":{
        "code":"40006",
        "msg":"Insufficient Permissions",
        "sub_code":"isv.illegal-client-ip",
        "sub_msg":"当前调用IP不在可信名单中"
    },
    "sign":"xxxxxxxxxx"
}


onlineServer