对比与迁移深度场景内容4 分钟阅读matrix

接口密钥与身份集成:按调用方与风险选路径

比较接口密钥与身份集成在调用主体、权限继承、日志追溯和凭据回收方面的差异,说明人机交互、系统调用与混合链路的选择条件,并列出轮换和交接时的检查项。

两条路径解决的是不同问题。接口密钥解决“程序怎么调”,身份集成解决“人是谁、权限从哪来”。混用两条路径,最后会得到一套既追不到人又管不住权限的接入。

两条路径的分工

对照材料:FastGPT 官方说明。

接口密钥是由平台签发、可设置有效期与使用限制的调用凭据,调用方在请求头里带上它访问接口,适合系统对系统的调用。身份集成走单点登录,专业版起支持,账号由已有系统创建,登录后进入应用,授权仍由应用内的组织架构与资源授权决定。

一条边界要先立住:密钥证明调用方,不证明自然人;单点登录证明自然人,不证明调用方。两者都在的链路,要说明以谁为准。

对照

维度接口密钥身份集成
证明对象调用方(系统)使用人(自然人)
凭据来源平台内创建,归属团队已有身份系统签发
回收方式轮换或删除密钥停用账号,并验证已有会话的退出策略
日志可追溯性追到密钥与团队追到具体人
适用场景定时任务、批量同步、系统间调用人机对话、审批、需留痕操作

按调用方判定

第一问是调用方是人还是程序。程序调用走密钥,人使用走身份集成,两者都不要的接入方式(例如公开分享链接)只适合试用,不适合正式业务。

第二问是操作是否留下业务后果。写单据、改状态、提交审批这类操作,日志要能追到人;只做查询的接口,追到密钥与团队通常足够。两问答完,路径基本确定。

凭据怎么管

密钥的关键落在归属与轮换,技术上并不复杂。三个问题要答:密钥归哪个团队、谁能创建、多久换一次。创建权限受团队默认权限开关影响:开关开启后新团队的全员组会增加创建权限,既有团队不自动补授,交接时要先看这条开关的实际状态。

轮换要有计划,并按计划演练一次。把轮换写进运维手册,注明责任人、周期与验证方式;没有计划的轮换,最后会变成“等出问题再换”,而出问题时往往密钥已经泄露了一段时间。

日志与审计的取舍

身份集成的日志完整度更高:谁在什么时候调用了哪个应用,记录到人。密钥调用的日志边界在调用方:能证明是哪个系统、哪个团队,无法证明操作者是谁。

这个差别在验收阶段会被追问。可行的折中是两层记录:应用日志按人记录,接口调用日志按系统记录,两边用同一个业务单号串起来。串起来之后,追查一次操作可以从业务单号回溯到具体调用,比只有一层日志更可靠。

混合路径的注意事项

最常见的混合是人在页面上操作、后台服务代为执行。这种设计里,页面身份与服务身份都要记录,并明确以谁为准。以服务身份为准的好处是实现简单,坏处是审批类操作的责任落不到人。

另一种混合是多个系统共用一个密钥。这种做法短期省事,长期的问题是配额无法归集、封禁一方影响全部。共用之前先把配额与影响面算清。

判定结论

三条结论可以直接用:人使用走身份集成,程序调用走密钥,涉及审批与写操作的身份必须可追溯到人。三条之外再加一条运维约定:每季度核对一次密钥清单与创建权限开关状态。核对记录本身就是审计材料。

密钥轮换怎么做

轮换分三步:先建新密钥并行使用,确认调用方切换完成,再停用旧密钥。三步之间的观察期不少于一个调用周期,避免定时任务刚好在切换窗口执行。轮换记录写明日期、旧密钥停用时间与验证方式,季度对账时按记录核一次。共用密钥的场景,轮换要提前通知全部调用方,否则会出现一方切换、其他方失败的中间态。

交接时的检查顺序

交接或轮岗时按三步检查:先看密钥清单与创建权限开关状态,再看身份集成的账号同步是否仍在运行,最后随机抽一条日志,看能否从业务单号追到具体调用。所需时间取决于凭据数量与身份系统,漏做一次则可能几个月无人发现权限早已过期。

数据来源

主题版本来源
单点登录与 OA 集成、组织架构分权当期商业方案FastGPT 商务咨询:授权、部署与支持范围
团队默认权限开关与 API Key 创建权限v4.17.3self-host/upgrading/4-17/4173