接入 BOSS

• Control 按 bes-control-service/docs/runbooks/operations.md 第 1 节做完迁移、密钥、同步目录和首位平台管理员初始化（bes-control seed-person）。
• 首位管理员初始化同时建好平台租户，code 为 BES_CONTROL_PLATFORM_TENANT_CODE，状态为 active。
• 测试台按 bes-api-console/docs/setup.md 登记，并能用平台管理员登录。
• 在 tenant.list 返回的 entries 中确认平台租户的 code 和 active 状态；有 next_cursor 时填入 cursor 继续查。

• SERVICE_ACCOUNT_ID 每次新生成，写进证书唯一的 URI SAN urn:bes:service:<uuid>；登记平台账号后它就是账号的 service_account_id。
• 私钥 boss-service-key.pem 放进 BOSS 部署的密钥存储。

前提：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"。

• 账号带 Control 的 platform-administrator 角色（role），在 service-account.list 里 product_id 为 null，能管所有产品（product）。
• --display-name 写 BOSS：测试台按这个名字找 BOSS 的平台账号。
• 重复执行保留同一个账号。

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

带：证书

请求：

GET https://id.test.globalbes.sg:9443/internal/control/v1/tenants?limit=100

返回：

HTTP/1.1 200 OK

{
  "entries": [
    {
      "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
      "code": "bes",
      "display_name": "BES",
      "status": "active",
      "created_at": "2026-01-01T08:00:00+00:00",
      "mfa_required": false
    }
  ],
  "next_cursor": null
}

程序发的请求和下面各环境的 curl 一样，可以先用它试。

• 返回 200 和租户列表：证书、地址和平台账号都对上。
• 地址：带证书的接口发到 https://id.test.globalbes.sg:9443，只带用户令牌的接口发到 https://id.test.globalbes.sg。
• 证书：TLS 客户端证书 boss-service.pem、私钥 boss-service-key.pem，用服务端 CA 验证 Control 的证书。
• 写操作：请求体带 request_ref，同一个 request_ref 重发返回第一次的结果。
• X-BES-Operator：可选，写代表哪个人操作的 person_id。
• 出错时返回 {"error": {"code": …, "reference": …, "message": …}}，程序按 code 分支。

错误：

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

填表的值：

{
  "request_ref": "create-boss",
  "code": "boss",
  "display_name": "BOSS",
  "scope_level": "tenant",
  "sellable": false,
  "status": "active"
}

返回：

{
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "code": "boss",
  "scope_level": "tenant",
  "sellable": false,
  "display_name": "BOSS",
  "status": "active",
  "version": 0
}

• 产品 boss 按租户（tenant）开通，scope_level 写 tenant。
• BOSS 是内部系统，不对客户售卖。

错误：

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

填表的值：

{
  "request_ref": "register-boss-web",
  "client_id": "boss-web",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "deployment_version": "1",
  "display_name": "BOSS",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://boss.example.com/callback"
  ],
  "post_logout_redirect_uris": [
    "https://boss.example.com/"
  ],
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "token_profile": "web",
  "dpop_required": false
}

返回：

{
  "client_id": "boss-web",
  "display_name": "BOSS",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://boss.example.com/callback"
  ],
  "post_logout_redirect_uris": [
    "https://boss.example.com/"
  ],
  "backchannel_logout_uri": null,
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "dpop_required": false,
  "token_profile": "web",
  "service_account_id": null,
  "status": "pending",
  "version": 0,
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "public_key_jwk": null,
  "deployment_version": "1",
  "client_secret": "<client_secret>"
}

• product_id 写 boss 产品的：登录后可选的租户和权限按这个产品的开通记录（entitlement）和角色算。
• redirect_uris 写 BOSS 实际的回调地址，逐字符一致。
• client_secret 只在这次返回里出现，放进 BOSS 部署的密钥存储；丢了就调 client.rotate-credential 换一个。
• 退出后回到 BOSS 的地址在这里登记，end-session 用它。

错误：

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

填表的值：

{
  "client_id": "boss-web",
  "request_ref": "activate-boss-web",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "status": "active"
}

返回：

{
  "client_id": "boss-web",
  "display_name": "BOSS",
  "kind": "confidential_web",
  "auth_method": "client_secret_basic",
  "redirect_uris": [
    "https://boss.example.com/callback"
  ],
  "post_logout_redirect_uris": [],
  "backchannel_logout_uri": null,
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "dpop_required": false,
  "token_profile": "web",
  "service_account_id": null,
  "status": "active",
  "version": 1,
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "public_key_jwk": null,
  "deployment_version": "1"
}

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

填表的值：

{
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "deployment_version": "1",
  "request_ref": "register-boss-features-1",
  "features": [
    {
      "code": "document.read",
      "route_template": "/documents/{id}",
      "method": "GET",
      "risk": "low",
      "display_name": "Read documents"
    },
    {
      "code": "document.write",
      "route_template": "/documents",
      "method": "POST",
      "risk": "low",
      "display_name": "Write documents"
    },
    {
      "code": "payment.approve",
      "route_template": "/payments/{id}/approve",
      "method": "POST",
      "risk": "high",
      "display_name": "Approve payments"
    }
  ]
}

返回：

[
  {
    "feature_id": "3d8a1b6f-c247-42a5-99f4-16eaf5c38c7b",
    "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
    "code": "document.read",
    "route_template": "/documents/{id}",
    "method": "GET",
    "risk": "low",
    "display_name": "Read documents",
    "deployment_version": "1",
    "status": "active"
  },
  {
    "feature_id": "4e9b2c70-d358-43b6-8a05-27fb06d49d8c",
    "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
    "code": "document.write",
    "route_template": "/documents",
    "method": "POST",
    "risk": "low",
    "display_name": "Write documents",
    "deployment_version": "1",
    "status": "active"
  },
  {
    "feature_id": "5fac3d81-e469-44c7-9b16-380c17e5ae9d",
    "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
    "code": "payment.approve",
    "route_template": "/payments/{id}/approve",
    "method": "POST",
    "risk": "high",
    "display_name": "Approve payments",
    "deployment_version": "1",
    "status": "active"
  }
]

• features 写 BOSS 自己的全部路由；BOSS 的功能清单：待定。
• 每次调用替换这个 deployment_version 的整份清单，所以每次都发全部功能。
• deployment_version 是 BOSS 验证请求时发的版本。

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

填表的值：

{
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "code": "document-controller",
  "request_ref": "define-boss-document-controller",
  "display_name": "Document controller",
  "feature_codes": [
    "document.read",
    "document.write"
  ]
}

返回：

{
  "role_id": "6abd4e92-f57a-45d8-8c27-491d28f6bfae",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "code": "document-controller",
  "display_name": "Document controller",
  "scope_level": "tenant",
  "feature_codes": [
    "document.read",
    "document.write"
  ],
  "status": "active",
  "tenant_id": null,
  "project_id": null,
  "version": 0
}

• 角色按 code 创建或整体替换；feature_codes 只能写 BOSS 已登记且 active 的功能码。

错误：

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

填表的值：

{
  "limit": 100
}

返回：

{
  "entries": [
    {
      "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
      "code": "bes",
      "display_name": "BES",
      "status": "active",
      "created_at": "2026-01-01T08:00:00+00:00",
      "mfa_required": false
    }
  ],
  "next_cursor": null
}

• 用本环境的 BES_CONTROL_PLATFORM_TENANT_CODE 在 entries 中找到平台租户，保存这一行的 tenant_id；本地代码为 bes。
• 有 next_cursor 时填入 cursor 继续查，找到后确认状态为 active。
• 创建开通记录和员工时填写这个 tenant_id。

错误：

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

填表的值：

{
  "request_ref": "create-bes-boss-entitlement",
  "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
  "entitlement": {
    "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
    "starts_at": "2026-01-01T00:00:00Z",
    "ends_at": "2036-01-01T00:00:00Z",
    "source": "internal",
    "source_ref": "seed-demo-boss",
    "source_version": 1
  }
}

返回：

{
  "entitlement_id": "c3a7e1f9-5b26-4d48-9a0c-e8f2b4d6a135",
  "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "project_id": null,
  "starts_at": "2026-01-01T00:00:00+00:00",
  "ends_at": "2036-01-01T00:00:00+00:00",
  "source": "internal",
  "source_ref": "seed-demo-boss",
  "source_version": 1,
  "seat_limit": null,
  "status": "pending",
  "readiness": "pending",
  "readiness_ref": null,
  "revoked_at": null,
  "version": 0
}

• 时段：同一租户、同一产品的时段不能重叠；ends_at 必填。
• source、source_ref、source_version 写这段时间出自哪份订单或合同。

错误：

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

填表的值：

{
  "entitlement_id": "c3a7e1f9-5b26-4d48-9a0c-e8f2b4d6a135",
  "request_ref": "activate-bes-boss-entitlement",
  "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "runtime_ready": true
}

返回：

{
  "entitlement_id": "c3a7e1f9-5b26-4d48-9a0c-e8f2b4d6a135",
  "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "project_id": null,
  "starts_at": "2026-01-01T00:00:00+00:00",
  "ends_at": "2036-01-01T00:00:00+00:00",
  "source": "internal",
  "source_ref": "seed-demo-boss",
  "source_version": 1,
  "seat_limit": null,
  "status": "active",
  "readiness": "ready",
  "readiness_ref": "4bf92f3577b34da6a3ce929d0e0e4736",
  "revoked_at": null,
  "version": 1
}

• runtime_ready: true 表示产品的运行环境已就绪。

错误：

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

填表的值：

{
  "request_ref": "create-staff-weiling-tan",
  "tenant_id": "4f2a9c6e-1b83-4d57-8e0a-c6d3b9f1a572",
  "display_name": "Tan Wei Ling",
  "channels": [
    {
      "channel_type": "email",
      "channel_identifier": "weiling.tan@bes.example.com"
    }
  ],
  "role_id": "6abd4e92-f57a-45d8-8c27-491d28f6bfae",
  "person_type": "staff"
}

返回：

{
  "person_id": "2c7e9b41-5d08-4a3f-b6e2-91f4a8c3d057",
  "membership_id": "6e1a4c9d-3f57-4b28-8d06-a2c7e5b1f938",
  "person_role_id": "f2c6ea04-8d57-4b93-ae2f-d5b9c3a7f480",
  "channel_identity_ids": [
    "7d3b9f15-2a68-4c04-b1e7-e8a2d6c4f591"
  ]
}

• person_type 写 staff，tenant_id 写平台租户的；员工只能建进平台租户，只有平台级服务账号能建。
• role_id 写 BOSS 的角色。管平台的员工另外要 Control 的 platform-administrator 角色，在平台租户里用 role-assignment.assign 分配；这个角色对所有租户生效。

错误：

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

填表的值：

{
  "request_ref": "first-login-weiling-tan",
  "person_id": "2c7e9b41-5d08-4a3f-b6e2-91f4a8c3d057",
  "purpose": "initial_login",
  "reason": "BOSS staff onboarding"
}

返回：

{
  "action_id": "4d9f2b6e-8a13-4c75-b2e0-f6a1c9d3e587",
  "purpose": "initial_login",
  "expires_at": "2026-01-03T08:00:00+00:00",
  "delivery": "queued"
}

• 返回只说明链接已排队发送；用 credential-action.get 和返回的 action_id 查是 pending、completed 还是 expired。
• 首次登录链接最长 48 小时有效。
• 员工首次登录要在手机验证器 App 上登记两步验证。

错误：

• client_secret 与私钥放密钥存储，BOSS 部署配置引用它们。

GET https://id.test.globalbes.sg/authorize?response_type=code&client_id=boss-web&redirect_uri=https%3A%2F%2Fboss.example.com%2Fcallback&scope=openid%20profile%20email&state=<state>&nonce=<nonce>&code_challenge=<code_challenge>&code_challenge_method=S256

• 端点地址从 GET https://id.test.globalbes.sg/.well-known/openid-configuration 读。
• state、nonce 每次随机生成，存在用户会话里。
• code_challenge = BASE64URL(SHA256(code_verifier))，只支持 S256；以上参数缺一个就被拒。
• 回调收到 ?code=…&state=…；code 60 秒内有效，只能用一次。
• Java 示例见「接入新产品」的「把用户跳到登录页」。

POST https://id.test.globalbes.sg/oauth/token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&code_verifier=<code_verifier>&redirect_uri=https%3A%2F%2Fboss.example.com%2Fcallback

HTTP/1.1 200 OK

{
  "access_token": "<access_token>",
  "id_token": "<id_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "openid profile email"
}

• access_token、refresh_token：存在服务端的用户会话里，浏览器只拿会话 cookie。
• access_token 有效 5 分钟。
• id_token 里的 sub 是这个人的 person_id，长期不变。

程序里发这个请求（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://boss.example.com/callback"
}

返回：

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"
}

• continue_url 必须与 boss-web 登记的 redirect_uris 或 post_logout_redirect_uris 之一完全一致。
• 把浏览器跳到 https://id.test.globalbes.sg + selection_url；员工选好后回到 continue_url?context_id=0f6b8d2e-4a17-4c93-9e5b-a1d27c4f3b68，把 context_id 存进服务端会话。
• 员工只能选平台租户 bes。
• 选择 5 分钟内有效；同一会话再发起一次会取消上一次。
• Java 示例见「接入新产品」的「让用户选租户」。

错误：

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

带：证书 + 用户的 access_token

请求：

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

{
  "product_id": "1d4b8e2f-6a35-4c71-9e08-b3f5a7c2d941",
  "context_id": "0f6b8d2e-4a17-4c93-9e5b-a1d27c4f3b68",
  "target": {
    "method": "GET",
    "path": "/documents/42",
    "deployment_version": "1"
  }
}

返回：

HTTP/1.1 200 OK

{
  "context": "<signed bes-context+jwt>",
  "checked_at": "2026-01-01T08:00:00.123456+00:00",
  "hard_expiry": "2026-01-01T08:00:30.123456+00:00",
  "action": "document.read",
  "risk": "low"
}

• 请求必须带 product_id，写 boss 的；BOSS 是平台级账号，不带会被拒绝。
• target.method、target.path：BOSS 收到的请求，不含查询串；deployment_version：登记功能清单时用的版本。
• context 用 https://id.test.globalbes.sg/.well-known/jwks.json 验证（ES256，类型 bes-context+jwt），aud 是 boss 的 product_id；claim features 是此人的全部功能码。
• Control 不可达、超时或返回 5xx 时拒绝请求。
• Java 示例见「接入新产品」的「验证每个请求」。

错误：

POST https://id.test.globalbes.sg/oauth/token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>

• 返回新的 access_token 和 refresh_token，两个都存下。
• 每个 refresh_token 只能用一次；旧的再用一次，整个会话被撤销。同一会话的刷新要串行。
• 网页会话空闲 2 小时或总共 12 小时后结束，刷新也不延长。

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

带：用户的 access_token

请求：

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

{
  "login_scope": "product"
}

返回：

HTTP/1.1 204 No Content

• login_scope: product（默认）登出 BOSS 所有登录客户端，client 只登出这一个。
• 先调这个接口，再清掉自己的会话。
• Java 示例见「接入新产品」的「结束登录」。

GET https://id.test.globalbes.sg/end_session?client_id=boss-web&state=<state>

• BES 显示确认页。要回到 BOSS，先给 boss-web 登记 post_logout_redirect_uris，再在这里带上 post_logout_redirect_uri。

• 在 BOSS 的用户菜单里加「Account settings」链接，在新标签页或约 560×760 的小窗口打开 https://id.test.globalbes.sg/account。
• 密码、两步验证、恢复码、已登录的浏览器、手机和邮箱、语言都在那里管理，BOSS 使用这个入口管理账户设置。
• 用户菜单只留：当前用户、切换公司（session.tenant-selection-start）、Account settings、登出（end_session）。

在 Control 部署配置的 event_consumers（环境变量 BES_CONTROL_EVENT_CONSUMERS）JSON 对象里配置接收方 boss：

{
  "boss": {
    "endpoint": "https://boss.local.globalbes.sg/internal/events/control",
    "audience": "boss-api",
    "event_types": [
      "entitlement.changed",
      "membership.joined",
      "membership.revoked",
      "role_assignment.changed",
      "channel_access.revoked",
      "invitation.created",
      "tenant.policy_changed",
      "person.status_changed",
      "role.defined",
      "role.changed",
      "support_grant.issued",
      "support_grant.closed"
    ]
  }
}

• audience 写 boss-api，event_types 与 bes-control-service/.env.example 中 boss 的 12 种事件一致，事件内容见契约仓 events/control/。

Control 每个事件发一个请求：

POST https://boss.local.globalbes.sg/internal/events/control
Content-Type: application/jwt
Idempotency-Key: 3e9a7c51-0b46-4d2f-9e83-a1c5f7d2b064

<event_jws>

• 请求体是 ES256 签名的 JWT，类型 bes-event+jwt，用 https://id.test.globalbes.sg/.well-known/jwks.json 验证；aud 是登记的 boss-api，5 分钟后过期。
• claim 是 common/event-envelope.json 的信封：event_id、event_type、aggregate_type、aggregate_id、tenant_id、product_id、sequence、occurred_at、trace_id、payload。
• 先按 event_id（主键）存下再回 2xx，之后从自己的表里处理；重复投递按 event_id 去重。
• 同一接收方的事件严格按顺序到达。没回 2xx 时 Control 从 30 秒起重试到 24 小时、共 10 次；之后这次投递保持失败，后面的事件都停住。