API 网关：采用认证信息标准化方案调用 API

[alex-smile]

背景

蓝鲸认证信息，是用于标识蓝鲸应用和用户的数据；调用者访问接入蓝鲸 API 网关的云 API 接口时，如果云 API 接口需要认证应用或用户，则请求时需要携带这些认证信息，才能正常发起请求。

目前，API 网关支持 2 种传递认证信息的方案：

• 方案一： 认证数据与请求参数放在一起，如放在 querystring、body 中 （不推荐）
• 方案二： 认证数据放在请求头 X-Bkapi-Authorization 中 （推荐）

采用方案一时，API 网关需要处理额外的任务，包括解析 querystring 和多种格式的 body（如 json、x-www-form-urlencoded、form-data 等）来获取认证信息，以及在向后端转发请求时，删除请求参数中的敏感数据（如 bk_app_secret、bk_token 等）。这存在以下问题：

• 1. API 网关需要解析请求参数，这对性能造成了重大消耗
• 2. 在 API 网关删除敏感参数的过程中，实际的请求参数被修改
• 3. 在整个请求过程中，请求参数可能被记录在日志中，带来敏感信息泄露的潜在风险

因此，推荐采用第二种方案进行认证信息的传递。目前正在使用第一种方案的调用者，也需要切换至第二种方案，并且去除请求参数中的蓝鲸认证信息（迁移方案参考下文）。

认证信息标准化方案

认证信息的标准化方案，即上文提到的第二个方案，可通过请求头 X-Bkapi-Authorization 传递认证信息，值为 JSON 格式字符串。

**注意：**二进制版本 open-paas/esb >= 2.12.20 支持 X-Bkapi-Authorization，应用调整时，需关注

• 1. 方案一：标注有此版本依赖；对应的蓝鲸运营大版本为 >= 6.0.5 版本，如果 open-paas 版本 < 2.12.20，访问 esb 组件会失败
• 2. 方案二：应用通过功能开关，设置是否将认证参数多传一份到请求参数

示例： 使用 curl 命令，请求时携带认证请求头

# 调用目标 API 开启: 应用认证+用户认证
curl -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}' "http://example.com/api"
# 用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

# 调用目标 API 开启: 应用认证
curl -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y"}' "http://example.com/api"
# 应用态 access_token 或用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

# 调用目标 API 开启: 用户认证
curl -H 'X-Bkapi-Authorization: {"bk_token": "x"}' "http://example.com/api"
# 用户态 access_token
curl -H 'X-Bkapi-Authorization: {"access_token": "x"}' "http://example.com/api"

示例： 使用 Python 语言和 requests 模块

import json
import requests

# 认证应用 + 用户
requests.get(
    "http://example.com/api",
    headers={
        "X-Bkapi-Authorization": json.dumps({
            "bk_app_code": "demo",
            "bk_app_secret": "secret",
            "bk_token": "your_token",
        })
    },
)

requests.get(
    "http://example.com/api",
    headers={
        "X-Bkapi-Authorization": json.dumps({"access_token": "abc"})
    },
)

X-Bkapi-Authorization 请求头所支持的全部字段如下表所示：

字段	类型	版本	描述
bk_app_code	string	开源版/上云版	应用 ID，可以通过蓝鲸开发者中心 -> 应用基本设置 -> 基本信息 -> 鉴权信息获取；网关 SDK 默认已添加
bk_app_secret	string	开源版/上云版	安全秘钥，可以通过蓝鲸开发者中心 -> 应用基本设置 -> 基本信息 -> 鉴权信息获取；网关 SDK 默认已添加
bk_token	string	开源版	用户登录态，用于认证用户；登录蓝鲸，对应 Cookies 中 bk_token 字段的值；提供 bk_token 时，不需要再提供 bk_username
bk_ticket	string	上云版	用户登录态，用于认证用户；登录蓝鲸，对应 Cookies 中 bk_ticket 字段的值；提供 bk_ticket 时，不需要再提供 bk_username
bk_username	string	开源版/上云版	当前用户用户名；仅用于应用免用户认证的场景中，用于指定当前用户。应用需向网关管理员申请免用户认证白名单，由于用户未经过校验，存在安全风险，请谨慎使用
access_token	string	上云版	用户态 access_token，或应用态 access_token

注意：

• 1. 认证应用：应用态 access_token、用户 access_token、 bk_app_code + bk_app_secret 三选一即可
• 2. 认证用户：用户态 access_token、bk_token 或 bk_ticket、bk_username 三选一即可；如果需要使用 bk_username，则应用需向网关管理员申请免用户认证

如何迁移到标准化认证信息方案

直接调用

• 请根据上文描述，将蓝鲸认证信息，从请求参数（querystring、body）中，切换到请求头 X-Bkapi-Authorization 中
• 旧版中，如果使用 app_code, app_secret, username 等蓝鲸认证参数，可将其原样迁移到 X-Bkapi-Authorization 中，或将其转换为新字段：app_code => bk_app_code, app_secret => bk_app_secret, username => bk_username，如 {"app_code": "x", "app_secret": "y", "username": "z"} 可转换为 {"bk_app_code": "x", "bk_app_secret": "y", "bk_username": "z"}

使用蓝鲸网关SDK/组件 SDK

• 使用开源版组件 API SDK：bkapi-component-open
• 网关 API SDK：如果当前请求存在问题，请联系网关管理员生成新版 SDK，并按照网关使用文档，切换到新版调用方式
• 上云版使用非 open SDK，需待 SDK 升级版本后，应用升级 SDK 版本，如 ieod 版本 SDK

注意：

1. 二进制版本 open-paas/esb >= 2.12.20 支持 X-Bkapi-Authorization，应用调整时，需关注
   • 1.1 方案一：标注有此版本依赖；对应的蓝鲸运营大版本为 >= 6.0.5 版本，如果 open-paas 版本 < 2.12.20，访问 esb 组件会失败
   • 1.2 方案二：应用通过功能开关，设置是否将认证参数多传一份到请求参数
2. bk_login 系统接口，参数 bk_username、bk_token 属于接口的普通参数，非网关的认证参数，需要放到请求参数中；如 bk_login/get_user, bk_login/is_login 组件
3. 组件系统 data 的接口，认证参数放到 x-bkapi-authorization 后，因后端接口逻辑要求，需要在请求参数中多传一个 bk_app_code（不需要传 bk_app_secret)

版本依赖

• 二进制版本：open-paas/esb >= 2.12.20
  • ESB 此版本开始支持请求头 X-Bkapi-Authorization 传递认证参数; 需要标注有此版本依赖，如果不能标注，可单独反馈，确认处理方案；对应的蓝鲸运营大版本为 >= 6.0.5 版本
• 容器化版本: 所有版本均支持

概念 & FAQ

请参考：#74