企业 SSO 集成
巴克励步
概述
Baklib 支持在 组织管理后台 安装 企业 SSO 登录 集成，让企业成员使用自有身份系统（IdP）授权登录组织工作台。与钉钉/企微 OAuth2 不同，本集成要求企业在自有系统中实现 OAuth 2.0 授权码模式 的三个端点：授权地址、Token 地址、用户信息地址。
另有一种 应用级 SSO：在单个应用的 访问控制 中配置，面向前台访客登录，见 访问控制与授权。本篇聚焦组织级集成。
操作步骤
步骤一：进入集成市场并安装
- 打开 组织管理后台 → 第三方集成 → 添加集成。
- 在集成市场找到 企业 SSO 登录（oauth2，说明：让企业用户通过企业自己的 SSO 系统账号授权登录）。
- 点击 安装，进入配置表单。
预期结果：看到应用 ID、授权地址、Token 地址等表单项。
步骤二：生成并填写集成参数
企业在 IdP 侧自行生成 应用 ID（app_id） 与 应用密钥（app_secret），并妥善保管。在 Baklib 表单中填写：
| 字段 | 说明 | 是否必填 |
|---|---|---|
| 应用 ID | 标识第三方应用，由企业生成 | 必填 |
| 应用密钥 | 校验第三方应用，由企业生成 | 必填 |
| 范围 | 限制权限，如 all 或 read_user |
必填 |
| 授权地址 | 企业 OAuth 授权页 URL，如 https://sso.example.com/oauth/authorize |
必填 |
| Token 地址 | 用授权码换取 access_token 的 URL | 必填 |
| 用户信息地址 | 用 token 获取用户资料的 URL | 必填 |
| 用户唯一标识字段 | 返回 JSON 中作为 Baklib 用户 ID 的字段名，默认 id |
可选 |
| 用户名称字段 | 显示名称字段，默认 name |
可选 |
| 用户头像字段 | 头像 URL 字段，默认 avatar 或 image |
可选 |
| 按钮文字 | 组织登录页按钮文案，默认「企业 SSO 登录」 | 可选 |
| 忽略来源验证 | 是否忽略 state 参数，默认否 | 可选 |
| 备注 | 后台识别用 | 可选 |
保存后，集成出现在 第三方集成 列表；组织登录页显示对应 SSO 按钮。
注意：应用 ID 与密钥仅用于企业 IdP 与 Baklib 之间的互信，勿泄露给无关人员。生产环境务必使用 HTTPS。
预期结果：集成保存成功；登录页出现企业 SSO 入口。
步骤三：企业侧实现 OAuth 端点
企业需在自有服务中实现标准 OAuth 2.0 授权码流程（旧站提供 Ruby 示例，其他语言同理）：
（1）授权地址
GET /oauth/authorize接收参数：
client_id、redirect_uri、response_type=code、scope、state。- 校验
client_id与redirect_uri白名单。 - 若用户未登录，跳转企业登录页；登录成功后生成 code（建议短期有效，如 5 分钟）。
- 重定向至 Baklib 回调地址，附带
code与state（除非勾选忽略来源验证）。
回调示例：
https://{组织域名}/-/oauth/corp/callback?code=xxx&state=yyy（2）Token 地址
POST /oauth/token接收：
code、grant_type=authorization_code、redirect_uri。- 校验 code 一次性有效后作废。
- 返回 JSON：
access_token、token_type=bearer、expires_in、scope。
（3）用户信息地址
GET /profile通过请求头
Authorization: Bearer {token} 传递 token。- 返回 JSON，字段名与表单中「用户唯一标识 / 名称 / 头像」映射一致，例如：
{
"id": "10001",
"name": "张三",
"image": "https://sso.example.com/avatar/10001.jpg"
}
预期结果：三项接口联调通过；Baklib 能完成授权并拉取用户资料。
步骤四：成员绑定 SSO 账号
成员首次使用企业 SSO 登录前，通常需完成账号绑定：
- 方式一：组织管理员在 用户管理 中进入成员 个人信息 → 账号绑定，点击已安装的 企业 SSO 完成绑定。
- 方式二：通过 Baklib 开放 API 绑定（适用于批量导入场景）。
绑定后，成员在组织登录页选择 企业 SSO 登录，按 IdP 提示授权即可进入工作台。
预期结果：绑定用户可通过 SSO 登录组织，未绑定用户按产品策略提示绑定或拒绝。
与应用访问控制 SSO 的区别
| 维度 | 组织级企业 SSO（本篇） | 应用级 SSO（07 访问控制） |
|---|---|---|
| 配置位置 | 组织管理后台 → 第三方集成 | 应用设置 → 访问控制 → 登录方式 |
| 登录对象 | 进入组织工作台的成员 | 访问单个应用前台的授权用户 |
| IdP 要求 | 企业自建完整 OAuth 三端点 | 常见 OAuth 2.0 IdP（填回调、Client ID/Secret） |
| 典型场景 | 统一企业身份进 Baklib 后台 | 客户门户、内网帮助中心前台门禁 |
两者可同时启用：成员用组织 SSO 进后台，访客用应用 SSO 进站点前台。
常见问题
Q：回调地址填什么？
A：以 Baklib 安装页或文档为准，一般为
A：以 Baklib 安装页或文档为准，一般为
https://{组织域名}/-/oauth/corp/callback；须在 IdP 应用的重定向 URL 白名单中登记。Q：安装后登录页没有 SSO 按钮？
A：确认集成已启用；成员访问的是正确组织域名登录页；若要求预绑定，检查账号绑定状态。
A：确认集成已启用；成员访问的是正确组织域名登录页；若要求预绑定，检查账号绑定状态。
Q：授权成功但提示用户不存在？
A：检查用户信息地址返回的 ID 字段是否与绑定记录一致；字段映射配置是否正确。
A：检查用户信息地址返回的 ID 字段是否与绑定记录一致；字段映射配置是否正确。