integration / auth-and-api
登录与对接
本地与社交登录、SSO（OIDC/SAML）联调清单、Webhook/API 集成模式与限流排错。
本页覆盖 终端用户如何进来 以及 业务系统如何与有谷乐学对话 两类问题。落地时请区分「预发联调」与「生产切流」，并在切换窗口准备回退预案。
登录方式总览
上线前联调清单（所有方式通用）
- 新用户首次登录 档案字段 是否齐全（姓名、学号绑定时机）。
- 老用户换设备：验证码/SSO 是否仍可合并到同一账号（避免重复学号）。
- 注销与退出：清理本地 token；SSO SLO（若需要）是否闭环。
- 弱网：超时提示是否友好；重试是否会重复发短信（成本与安全）。
单点登录（SSO）
常见协议选择
联调步骤（推荐顺序）
在 IdP 创建测试应用，记录 client_id / secret 或上传 SP 元数据，线下保存轮换日程。
在有谷管理后台填入 回调 URL、Issuer、JWKS/证书，与环境（预发/生产）一一对应，禁止混用。
用 2 个测试账号：一个新映射、一个已绑定，验证首次登录与重复登录。
测 令牌过期与刷新：长时间挂起页面后再操作不应无声失败。
测 注销链路：是否需要回到 IdP 注销页；财务/隐私场景常强制要求。
账户映射与字段
- NameID / email / employeeNumber 哪个作为稳定键，需与 HR 主数据一致。
- 若 IdP 改名改邮，平台侧合并规则要提前定义，避免学档分裂。
常见故障速查
不同版本对 SAML Attribute 命名、OIDC claim 的路径可能不同，以实施顾问提供的映射表为准。上线后若 IdP 变更元数据，应走变更工单而非口头修改。
开放接口与用量限制
典型集成场景
- 成员同步：从 HR 或教务系统批量创建/更新用户与班级关系。
- 内容回写：外部 LMS 或有谷为唯一内容源时的课程元数据对齐。
- 进度回调：任务完成、考试交卷触发下游积分或 HR 证明。
- 只读报表：BI 系统定时拉取聚合指标。
鉴权模式
- API Key：适合服务间；配合 IP 白名单与密钥轮换。
- OAuth 客户端：适合多第三方、需要按应用限权时。
密钥应保存在 密钥管理系统，勿写入前端仓库或共享文档。
限流与批量策略
环境与域名
- Base URL、密钥、回调 在预发与生产完全隔离。
- 网络侧：若调用方在自建机房，需放行 出网白名单 与 TLS 检查。
若控制台未展示 完整 OpenAPI 与配额，通过工单索取带版本号的文档；对接时注明 API 版本号 避免静默升级破坏兼容。
安全与合规补充
- 回调接口必须 验签 或 TLS 客户端证书（以文档为准）。
- 日志中过滤 token 与 PII；对接方保存最小必要字段。
更全面的组织安全策略见 安全与合规。
