接入旧产品

在测试台点本步的 Product Create 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "request_ref": "create-cost",
  "code": "cost",
  "scope_level": "tenant",
  "display_name": "Cost Control"
}

返回：

{
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "code": "cost",
  "scope_level": "tenant",
  "sellable": true,
  "display_name": "Cost Control",
  "status": "active",
  "version": 0
}

• code：小写字母开头，只用小写字母、数字和 _.-，登记后不再改。

错误：

在测试台点本步的 Client Register 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "request_ref": "register-cost-proxy",
  "client_id": "cost-proxy",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "deployment_version": "legacy-v1",
  "display_name": "Cost Control",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://cost.example.com/oauth2/callback",
    "https://cost.example.com/bes/tenant-chosen"
  ],
  "scopes": [
    "openid",
    "profile"
  ],
  "token_profile": "web",
  "dpop_required": false
}

返回：

{
  "client_id": "cost-proxy",
  "display_name": "Cost Control",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://cost.example.com/oauth2/callback",
    "https://cost.example.com/bes/tenant-chosen"
  ],
  "post_logout_redirect_uris": [],
  "backchannel_logout_uri": null,
  "scopes": [
    "openid",
    "profile"
  ],
  "dpop_required": false,
  "token_profile": "web",
  "service_account_id": null,
  "status": "pending",
  "version": 0,
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "public_key_jwk": null,
  "deployment_version": "legacy-v1",
  "client_secret": "<client_secret>"
}

• 每个旧产品一个登录客户端。
• redirect_uris：代理的回调 https://<旧产品主机>/oauth2/callback，逐字符一致；选租户（tenant）的回调也要登记在这里。
• client_secret 只在这次返回里出现，存成代理读取的文件 /run/secrets/oidc-client。

错误：

在测试台点本步的 Client Set Status 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "client_id": "cost-proxy",
  "request_ref": "activate-cost-proxy",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "status": "active"
}

返回：

{
  "client_id": "cost-proxy",
  "display_name": "Cost Control",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://cost.example.com/oauth2/callback",
    "https://cost.example.com/bes/tenant-chosen"
  ],
  "post_logout_redirect_uris": [],
  "backchannel_logout_uri": null,
  "scopes": [
    "openid",
    "profile"
  ],
  "dpop_required": false,
  "token_profile": "web",
  "service_account_id": null,
  "status": "active",
  "version": 1,
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "public_key_jwk": null,
  "deployment_version": "legacy-v1"
}

在测试台点本步的 Service Account Create 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "request_ref": "create-cost-gateway-account",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "display_name": "Cost gateway"
}

返回：

{
  "service_account_id": "7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "registered_client_id": "svc-7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "display_name": "Cost gateway",
  "certificate_fingerprint": null,
  "not_before": null,
  "not_after": null,
  "previous_fingerprint": null,
  "previous_fingerprint_valid_until": null,
  "status": "pending",
  "version": 0,
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "control_role_id": "2e7f9a04-5c1b-4d83-a6f2-0b9c8d7e1a35",
  "role_id": "8b4d2f6a-3c71-4e95-a0d8-f6b2c4e8a137"
}

• 账号给代理后面的私有网关用，带 Control 的 product-runtime 角色（role）。
• 返回的 status 是 pending，登记证书后再启用。

CERT_DIR="$HOME/bes-certs/cost-gateway"
mkdir -p "$CERT_DIR"
SERVICE_ACCOUNT_ID=7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364   # 换成上一步返回的 service_account_id
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -subj "/CN=Cost gateway" \
  -addext "subjectAltName=URI:urn:bes:service:$SERVICE_ACCOUNT_ID" \
  -addext "basicConstraints=critical,CA:FALSE" \
  -addext "keyUsage=critical,digitalSignature" \
  -addext "extendedKeyUsage=clientAuth" \
  -keyout "$CERT_DIR/gateway-key.pem" -out "$CERT_DIR/gateway.csr"

• 证书唯一的 URI SAN 是 urn:bes:service:<service_account_id>。
• 私钥 gateway-key.pem 放进部署的密钥存储。

前提：OpenSSL 3.0 及以上，openssl version 显示 OpenSSL 3.x。Mac 自带的 /usr/bin/openssl 是 LibreSSL，不认 -copy_extensions：先执行 brew install openssl@3，再执行 export PATH="$(brew --prefix openssl@3)/bin:$PATH"。

CERT_DIR="$HOME/bes-certs/cost-gateway"
openssl x509 -in "$CERT_DIR/gateway-cert.pem" -outform DER | openssl dgst -sha256 | awk '{print $NF}'
openssl x509 -in "$CERT_DIR/gateway-cert.pem" -noout -startdate -enddate

• 第一行输出是 certificate_fingerprint：证书 DER 编码的 SHA-256，64 位十六进制。
• notBefore= 后的时间是 certificate_not_before，notAfter= 后的是 certificate_expires_at，改写成 RFC 3339 UTC，例如 Jan 1 08:00:00 2026 GMT 写成 2026-01-01T08:00:00Z。
• 证书和私钥拷成网关读取的 /run/secrets/gateway-cert、/run/secrets/gateway-key。

在测试台点本步的 Service Account Register 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "service_account_id": "7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "request_ref": "register-cost-gateway-certificate",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "display_name": "Cost gateway",
  "certificate_fingerprint": "<certificate_fingerprint>",
  "certificate_not_before": "2026-01-01T08:00:00Z",
  "certificate_expires_at": "2028-04-05T08:00:00Z"
}

返回：

{
  "service_account_id": "7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "registered_client_id": "svc-7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "display_name": "Cost gateway",
  "certificate_fingerprint": "<certificate_fingerprint>",
  "not_before": "2026-01-01T08:00:00+00:00",
  "not_after": "2028-04-05T08:00:00+00:00",
  "previous_fingerprint": null,
  "previous_fingerprint_valid_until": null,
  "status": "pending",
  "version": 1,
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "control_role_id": "2e7f9a04-5c1b-4d83-a6f2-0b9c8d7e1a35",
  "tenant_id": null,
  "project_id": null,
  "role_id": "8b4d2f6a-3c71-4e95-a0d8-f6b2c4e8a137"
}

• product_id、display_name 与创建服务账号时相同；指纹和有效期取上一步算出的值。

错误：

在测试台点本步的 Service Account Set Status 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "service_account_id": "7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "request_ref": "activate-cost-gateway-account",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "status": "active"
}

返回：

{
  "service_account_id": "7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "registered_client_id": "svc-7f3c1a9e-4b62-4d85-9e17-c0a8d5b2f364",
  "display_name": "Cost gateway",
  "certificate_fingerprint": "<certificate_fingerprint>",
  "not_before": "2026-01-01T08:00:00+00:00",
  "not_after": "2028-04-05T08:00:00+00:00",
  "previous_fingerprint": null,
  "previous_fingerprint_valid_until": null,
  "status": "active",
  "version": 2,
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "control_role_id": "2e7f9a04-5c1b-4d83-a6f2-0b9c8d7e1a35",
  "tenant_id": null,
  "project_id": null,
  "role_id": "8b4d2f6a-3c71-4e95-a0d8-f6b2c4e8a137"
}

• 没登记证书或证书已过期时不能启用。

在测试台点本步的 Feature Register 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "deployment_version": "legacy-v1",
  "request_ref": "register-cost-entry",
  "features": [
    {
      "code": "legacy.entry",
      "route_template": "/legacy-entry",
      "method": "GET",
      "risk": "low",
      "display_name": "Enter Cost Control"
    }
  ]
}

返回：

[
  {
    "feature_id": "9c5e3a7b-4d82-4fa6-b1e9-07c3d5f9b248",
    "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
    "code": "legacy.entry",
    "route_template": "/legacy-entry",
    "method": "GET",
    "risk": "low",
    "display_name": "Enter Cost Control",
    "deployment_version": "legacy-v1",
    "status": "active"
  }
]

• 只登记这一个功能：code legacy.entry、method GET、route_template /legacy-entry、deployment_version legacy-v1、risk low。
• 进入后能做什么，仍由旧产品自己决定。

在测试台点本步的 Role Define 标签，按下面的值填表（id 用前面步骤返回的），点 Send request。

填表的值：

{
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "code": "cost-user",
  "request_ref": "define-cost-user",
  "display_name": "Cost Control user",
  "feature_codes": [
    "legacy.entry"
  ]
}

返回：

{
  "role_id": "0e6f4b8c-5a93-40b7-82fa-18d4e6a0c359",
  "product_id": "8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246",
  "code": "cost-user",
  "display_name": "Cost Control user",
  "scope_level": "tenant",
  "feature_codes": [
    "legacy.entry"
  ],
  "status": "active",
  "tenant_id": null,
  "project_id": null,
  "version": 0
}

• 能进入旧产品的每个角色的 feature_codes 都要有 legacy.entry。

• 模板在 bes-infra 的 components/oauth2-proxy/：oauth2-proxy.cfg、nginx.conf.template、compose.example.yaml；镜像 quay.io/oauth2-proxy/oauth2-proxy:v7.15.4。
• 环境变量：OAUTH2_PROXY_OIDC_ISSUER_URL 写 https://id.test.globalbes.sg，OAUTH2_PROXY_CLIENT_ID 写 cost-proxy，OAUTH2_PROXY_REDIRECT_URL 写 https://cost.example.com/oauth2/callback，OAUTH2_PROXY_UPSTREAMS 写下一步的私有网关，OAUTH2_PROXY_COOKIE_NAME 写 __Host-cost-rp（不设 cookie 域），再加 Redis 连接。
• 每个产品一个登录客户端、一个 cookie 名、一个 Redis 命名空间。

程序里发这个请求（id 用前面步骤返回的）：

带：证书 + 用户的 access_token

请求：

POST https://id.test.globalbes.sg:9443/api/sessions/tenant-selection
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "continue_url": "https://cost.example.com/bes/tenant-chosen"
}

返回：

HTTP/1.1 201 Created

{
  "selection_id": "9c4e1b7a-2d58-4f3c-b6a0-e81d5f2c7a94",
  "selection_url": "/tenants?selection=9c4e1b7a-2d58-4f3c-b6a0-e81d5f2c7a94",
  "expires_at": "2026-01-01T08:05:00+00:00"
}

• 模板只读这个 cookie，不发起选择；这一步加在代理一侧。
• 用户的 access_token 取 oauth2-proxy 传来的 X-Forwarded-Access-Token（pass_access_token = true），带网关证书调用。
• continue_url 必须与 cost-proxy 登记的 redirect_uris 之一完全一致。
• 把浏览器跳到 https://id.test.globalbes.sg + selection_url；用户选好租户后回到 https://cost.example.com/bes/tenant-chosen?context_id=0f6b8d2e-4a17-4c93-9e5b-a1d27c4f3b68。
• 把 context_id 写进 cookie __Host-BESLegacyContext（Secure、Path=/、不设 Domain）。
• 选择 5 分钟内有效。

错误：

程序里发这个请求（id 用前面步骤返回的）：

带：证书 + 用户的 access_token

请求：

GET https://id.test.globalbes.sg:9443/internal/auth/validate
Authorization: Bearer <access_token>
X-BES-Product: 8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246
X-BES-Legacy-Identity: true
X-BES-Context-Id: 0f6b8d2e-4a17-4c93-9e5b-a1d27c4f3b68
X-Original-Method: GET
X-Original-URI: /legacy-entry
X-Original-Host: cost.example.com
X-BES-Deployment-Version: legacy-v1

返回：

HTTP/1.1 200 OK

• 网关是代理和旧产品之间的私有 nginx，带网关证书调 https://id.test.globalbes.sg:9443；这个接口只返回状态码和响应头，没有响应体。
• 200：放行，并把返回头 X-BES-Person-Id、X-BES-External-Id、X-BES-Tenant-Id 传给旧产品。
• 401：登录已结束或令牌无效，让用户重新登录。
• 403：拒绝，原因在返回头 X-BES-Auth-Reason：access_denied 没有进入权限，entitlement_missing 租户没有有效的开通记录（entitlement），target_unknown 先登记 legacy.entry 功能。
• 其他状态和超时一律拒绝。
• cookie __Host-BESLegacyContext 为空（还没选租户）时，网关直接返回 403。
• 能自己发 HTTP 请求的产品可以改用 session.validate，见「接入新产品」的「验证每个请求」。

• X-BES-Person-Id：BES 的 person_id。
• X-BES-Tenant-Id：验证过的租户。
• X-BES-External-Id：此人在本产品、本租户的旧用户 id，UTF-8 百分号编码，先解码；没有对应时为空。
• 只信网关发来的这三个头，外部请求带来的同名头丢掉。
• X-BES-External-Id 为空表示旧账号没导入，按这个状态显示。
• 对应关系只在 Control 主机上导入旧账号时写入：bes-control import-people，文件格式 control/legacy-import.jsonl.schema.json。

程序里发这个请求（id 用前面步骤返回的）：

带：证书

请求：

GET https://id.test.globalbes.sg:9443/internal/control/v1/identity-links?product_id=8a3e5c17-2f94-4b6d-a0c8-5e71d9b3f246&tenant_id=7c0e2a5e-3b1f-4d6a-9a53-1f2f6d0c8a11&person_id=5a9d3c1b-7e24-4f60-b8a1-c03e6d2f9475

返回：

HTTP/1.1 200 OK

{
  "external_id": "legacy-user-10482"
}

• external_id: null 表示没有有效的对应。