上游 SSO 凭证登录

有些上游（如 Kiro）不接受静态 API key，而要你用 OAuth 登录拿一份会过期的刷新凭证。网关转发请求时，得拿这份凭证去换一个临时 access token、塞进发往上游的请求头。本页讲管理员怎么一次性把这份凭证登录下来、导进网关。

无需手工建上游：登录本身就是全部操作——首次登录会自动创建厂商对应的上游，此后的登录把新账号的凭证追加到同一个上游下。已登录后，可在控制台 → 上游 → 该 SSO 上游（带 SSO 徽标）→ 凭证区块里查看各账号凭证的状态，或复制那条 docker run … login … 命令继续加账号。

核心机制：登录发生在管理员本机，不在网关。网关是远端服务，接不住浏览器回环重定向；所以网关镜像自带一个 login 子命令，你在自己机器上跑它——它在本机拉起一个临时监听接住浏览器回调、完成 OAuth 授权、拿到刷新凭证后，用控制台访问密钥调网关的导入 API 把凭证上报，随即退出、不落地任何凭据。网关全程只接收一个已铸好的凭证，暴露面最小。

别和 配置 SSO 企业登录 搞混：那一页讲『用企业 IdP 认证调用网关的人』（数据面 token / 控制台企业登录）；本页讲『管理员登录上游厂商（如 Kiro）拿一份网关转发用的刷新凭证』。方向相反：一个认证进网关的流量，一个给网关去上游用。

第一步：先配好控制台访问密钥

这是前置条件，没配整条流程会卡在 401。login 子命令向网关认证用的是控制台访问密钥（web_console.secret_key），不是数据面 client access key。

网关配置 [web_console] 段的 secret_key 是一把长期有效的静态密钥（bcrypt 哈希存储），命中即注入完全管理员权限。配置要求：

• 非空且 ≥ 12 字符，否则配置校验直接报错；
• 默认未配置（None），不会自动生成，必须手动设置；
• 数据库存储模式下，在 server.toml 的 [web_console] 段写 secret_key = "你的密钥"；Docker 镜像通过环境变量 CONSOLE_SECRET_KEY 注入。

⚠️ 这把密钥 = 完全管理员权限。传递用环境变量或 :ro（只读）文件挂载、用完即删；不要写进命令行参数、版本控制或聊天记录。

第二步：确认容器能连到网关控制台

login 容器要把导入请求发到网关控制台。控制台的远端访问由 allow_remote 控制，注意两层默认值不同：配置文件默认 false（只放行本机回环），而官方 Docker 镜像经 CONSOLE_ALLOW_REMOTE=true 默认放行远程（见 环境变量配置参考 与 控制台登录与角色 → 安全）。若你的网关按默认 false 生效（如 bare metal / 源码运行），容器经网桥网络连过来的源 IP 不是回环，会被挡成 403。两条通路二选一：

1. docker run --network host（推荐，默认配置不动）：容器共享宿主网络，源 IP 即回环，默认配置即可放行。
2. allow_remote = true（改网关配置）：放开控制台的远端访问。注意这会扩大控制台暴露面，且同机反向代理下来源 IP 是 127.0.0.1、既有检查挡不住经代理进来的远端客户端——既有语义，非本次引入。

检查依据是 TCP 对端地址，不看 X-Forwarded-For，所以 --network host 是最省心的。

第三步：运行登录命令

在能打开浏览器的机器上跑下面的命令。访问密钥经环境变量传入；login 刻意不提供 --access-key <明文> 这类命令行参数形式——命令行参数会进 ps 进程列表、shell history 与 docker inspect，密料不落命令行。--entrypoint protoflux 必须显式写明，否则 lima/colima 这类 Docker wrapper 会把裸 login 当宿主命令解析，去执行系统的 /usr/bin/login（报错 Cannot possibly work without effective root）：

docker run --rm -it --network host \
  --entrypoint protoflux \
  -e PROTOFLUX_ACCESS_KEY='<secret_key 的值>' \
  <网关镜像> login \
    --vendor kiro \
    --gateway http://localhost:7890

把 <网关镜像> 换成你部署网关用的那个镜像引用——就是 Docker 单机跑通 第 1 步 docker pull / docker run 用的同一个镜像（官方发布版形如 ghcr.io/<组织>/<镜像>:<tag>）。login 子命令内置在这个镜像里，无需另装。

参数说明：

参数	含义
-e PROTOFLUX_ACCESS_KEY=<值>	第一步配好的 secret_key，经环境变量传入（推荐方式）
--vendor kiro	要登录的上游 SSO 厂商 id，与上游表单里选的 sso_vendor 一致
--gateway http://localhost:7890	网关控制台地址。--network host 下用 localhost；否则换成宿主 IP 或 host.docker.internal。必须是 https，或 http + 回环/私网地址——公网明文 http 一律拒绝
--account <账号>（可选）	该凭证的账号标识（如登录邮箱）。同名重登替换旧凭证，不同名追加新账号。缺省自动取厂商返回的账号身份；厂商不给时落"未命名账号"槽位
--upstream-id 7（可选）	目标上游的稳定 id（控制台上游列表里能看到的数字 id）。一般不用填：缺省时网关自动解析或创建该厂商的上游
--port 3128（可选）	本机回调监听端口。缺省自动选厂商 IdP 白名单里的第一个空闲端口（kiro 白名单首项 3128——IdP 只认官方 IDE 注册的固定端口集，临时端口会被拒）。用 docker -p 127.0.0.1:3128:3128 发布端口时须钉死同一白名单端口并保持一致；--network host 下可省略
--access-key-file <容器内路径>（可选）	环境变量的替代档：把密钥存成本地文件，-v /path/to/key.txt:/key:ro 只读挂载后用本参数指向它（适配 docker secret 等文件型密钥管理）

密钥取值三档（按此顺序）：--access-key-file 文件 → 环境变量 PROTOFLUX_ACCESS_KEY → 都没有则无回显交互输入。三档都不经命令行参数。

命令跑起来后会发生这些事：它在本机回环白名单端口（kiro 默认首个空闲的 3128）拉起临时监听 → 打开浏览器跳去 IdP 登录 → 你在浏览器里完成授权 → IdP 带授权码回跳本机监听 → 子命令用 PKCE（Proof Key for Code Exchange）换到刷新凭证 → 调网关导入 API 上报 → 退出。全程刷新凭证不落你本机、不进网关日志。

容器内通常唤不起浏览器，命令会把授权 URL 打印出来，复制到宿主浏览器打开即可。

企业登录：IAM Identity Center（AWS IDC）

上面的 PKCE 流程覆盖 Kiro 门户里的 Builder ID、Google、GitHub 等社交登录。如果你的企业用 AWS IAM Identity Center（原 AWS SSO）管理 Kiro 访问，登录走的是同一个 login 命令、同一个门户入口，区别只在浏览器里选哪种登录方式——命令本身不用加任何参数，CLI 会根据门户回调的形状自动分流。

操作步骤：

1. 照常跑 login --vendor kiro …，浏览器打开 Kiro 门户登录页；
2. 在登录页选 IAM Identity Center（而非 Builder ID / Google / GitHub）；
3. 按提示输入管理员给你的企业 start URL（形如 https://d-example12345.awsapps.com/start 的 AWS IDC 租户地址，具体值由企业管理员提供）；
4. 门户回跳本机监听——这次回调不带授权码，而是带 login_option=awsidc + 企业 start URL + IDC 区域。CLI 识别到这个中间回调后，会回浏览器一个"正在完成设备授权"页面，随后在终端打印一条设备验证链接；
5. 打开那条验证链接（或终端打印的 URL），在浏览器里完成设备授权；
6. 授权完成后，CLI 拿到 access token + refresh token，照常上报网关。

技术上的区别（管理员通常无需关心，仅供排查）：社交登录的凭证刷新打 Kiro 桌面端点；IDC 凭证的刷新打 AWS SSO-OIDC 的 oidc.{区域}.amazonaws.com/token，且每个企业的 IDC 区域不同——CLI 会把企业 start URL 和 IDC 区域随凭证一起存进网关，续期时按凭证读取，不用你配置。导入的 IDC 凭证行 来源 列显示 kiro_idc，社交登录显示 kiro_desktop，两种凭证可在同一个 Kiro 上游下并存、网关自动轮换。

IDC 凭证 90 天需重登：服务器后台任务会自动续期 access token（每 60 秒扫描、提前 5 分钟刷新），续的是 access token，不是客户端密钥。设备流程注册的 OIDC 客户端密钥（client_id/client_secret）有效期约 90 天，到期后刷新会开始失败——此时刷新无法自动恢复（重试仍用同一对过期密钥），凭证会转成终态并标注"客户端密钥过期，需重新登录"。届时重新跑一次上面的登录命令（同一个账号会替换旧凭证）即可，无需删旧行。社交登录凭证不涉及客户端密钥，无此限制。

多账号：多登录一次就多一个账号

一个厂商（如 kiro）在网关里始终只有一个上游，下面挂多个账号的凭证——和"一个上游配多把 API key"是同一逻辑，网关自动在几个账号之间轮换分摊请求。再加一个账号 = 把上面的登录命令再跑一遍（用另一个账号完成授权）：

• 新账号的凭证追加到同一个上游下，即刻参与轮换，无需重启或改配置；
• 想让各行能明确区分，加 --account 邮箱或别名；缺省自动取厂商返回的账号身份；
• 同一个账号重新登录（--account 相同，或厂商返回的身份相同）会替换该账号的旧凭证——凭证失效时重新登录一次即可修复。

账号凭证的管理（查看 / 删除）

控制台 → 上游 → 点开该 SSO 上游 → 凭证区块列出每个账号一行：账号标识、状态（active / expired / error）、来源、过期时间。

• 删除某个账号：点该行右侧的删除图标，再点"删除"确认。删除后该账号立刻不再承接流量、网关也不再替它续期；想恢复时重新登录导入即可。
• 删除只影响这一个账号行，同上游的其他账号不受影响。

凭证由网关自动续期

凭证导入后不需要任何维护：网关后台任务在到期前主动续期（默认每 60 秒扫描一次、提前 5 分钟刷新），即使该上游长期没有流量也不会让凭证静默过期。续期偶尔失败时网关自动退避重试；状态为 error 的行会自愈，不需要人工干预——唯一需要人处理的是凭证被上游吊销（状态 revoked，通常是长时间未续期或在上游侧主动登出），此时重新跑一次登录命令导入即可。

多实例部署同样无需配置：各实例自动互斥（每个凭证同一时刻只有一个实例在续期），续期结果自动传播到其余实例。相关参数（sso_credentials.*）见 环境变量配置参考 → 仅配置文件可配的字段，默认值即可用。

兜底：手动托举

登录失败（IdP 端点行为变化、网络问题等）时，可以走手动托举：在 Kiro 官方界面/客户端完成登录，把产生的刷新凭证复制下来，在控制台上游凭证区块的"手动粘贴"框里贴进去点导入（可顺带给一个账号标识，用于多账号去重）。零脚本、零登录端点依赖，是任何厂商的通用兜底。

排查

• 401：secret_key 没配（web_console.secret_key 为空，控制台 API 未启用）或值不匹配。两者后端无法区分，错误文案同时列出两种可能。
• 403：控制台远端访问被拒。用 --network host，或在网关配置设 allow_remote = true。
• 密钥刚改了还认旧值：verify_bearer 有 300 秒正向缓存（以 token 哈希为 key），轮换后旧密钥最长 300 秒内仍可能有效；超时后自动失效。
• 连续试错被 ban：控制台有失败计数与 IP 封禁。排错换密钥试错多次会触发，等封禁时长过后再试或换 IP。
• 回调收不到：确认 --port 与 docker -p 映射一致、端口没被占用；--network host 下无需 -p。
• 浏览器报 redirect_mismatch：回调端口不在厂商 IdP 白名单里。缺省行为已自动选白名单端口；若手动指定了 --port，改成白名单内的（kiro：3128、4649、6588、8008、9091 等）。
• Cannot possibly work without effective root：命令没写 --entrypoint protoflux，lima/colima 等 Docker wrapper 把裸 login 解析成了系统命令 /usr/bin/login（非特权拒绝）。补上 --entrypoint protoflux 即可。

运维须知

• 经 secret_key 上报的导入操作，审计日志里 actor 统一记为 secret_key，无法区分是哪个工具/哪次登录发起的。
• 这把密钥命中即完全管理员权限，属长期高权限凭证：:ro 挂载、用完即删；轮换走改配置 + 重载（注意 300 秒缓存窗口）。
• 导入的刷新凭证用主密钥 ENCRYPTION_KEY 加密存数据库；网关未配它时拒绝工作（fail-closed，而非明文降级）。没配的话先 openssl rand -hex 32 生成一把并带上它重启，见 环境变量配置参考 → ENCRYPTION_KEY——务必备份，丢了已加密的凭证永久不可读。

下一步：配置 SSO 企业登录 看反方向——用企业 IdP 认证调用网关的人；上游与模型字段 看上游完整字段；端点 · 认证 · 协议互通 看认证顺序全景。