飞书单点登录示例(OIDC)¶
管理员可以将飞书设为身份提供商(IdP),让员工使用飞书账号登录指定的观测云工作空间。请先在飞书创建应用,再在观测云添加身份提供商,最后回填地址并用员工账号验证登录。
选择接入方式¶
飞书开放平台和飞书集成平台(AnyCross)都可以用于配置观测云单点登录。
| 飞书应用的创建入口 | 在观测云选择的配置方式 |
|---|---|
| 飞书开放平台开发者后台的「企业自建应用」 | 按飞书开放平台接入,上传非标准 OIDC 配置文件。 |
| 飞书集成平台(AnyCross)「身份集成」中的单点登录应用 | 按飞书集成平台接入,根据应用的 Token 认证方式选择标准或非标准 OIDC。 |
开始前,请确认您有目标工作空间的 SSO 管理权限,以及创建、配置飞书应用所需的权限。准备一个用于验证的飞书员工账号,并确认该账号对应的企业邮箱和域名,例如 alice@example.com 和 example.com。如涉及应用审批,请联系飞书企业管理员。
飞书开放平台接入¶
1. 创建企业自建应用,获取凭证¶
- 打开飞书开放平台开发者后台,登录目标企业,点击创建企业自建应用。
- 填写应用名称(例如「观测云单点登录」)、应用描述和图标,点击创建。
- 进入应用的凭证与基础信息,在应用凭证中复制 App ID 和 App Secret,供下一步配置使用。
- 如需在飞书工作台提供入口,点击添加应用能力,找到网页应用并点击添加。主页地址在取得观测云的发起登录 URL 后填写。
2. 在飞书开通权限¶
进入应用的开发配置 > 权限管理,点击开通权限,按下表搜索并开通配置文件所用的权限。
| 在飞书中搜索的权限 | 权限标识 | 权限类型 | 用途 |
|---|---|---|---|
| 获取成员名片信息 | component:user_profile |
用户身份 | 获取登录员工的基本信息。 |
| 获取用户邮箱信息 | contact:user.email:readonly |
应用身份 | 获取用于关联 SSO 账号的邮箱。 |
| 获取用户 user ID | contact:user.employee_id:readonly |
应用身份 | 获取飞书用户 ID,属于下方模板的示例授权范围。 |
若业务需要同步手机号,可开通获取用户手机号(contact:user.phone:readonly)。将该权限加入配置文件的 scope,在 claimMapping 中增加 "mobile": "mobile",登录后核对手机号是否取到。如权限需要配置可访问的数据范围,确认验证账号在该范围内。申请、审核和发布流程见飞书权限开通指南。
3. 在观测云上传配置文件¶
-
准备 JSON 文件。 复制下方飞书开放平台 JSON 模板中的完整 JSON,保存为
feishu-oidc.json。在文件中填写或核对以下字段。JSON 字段 填写内容 clientId填写飞书应用凭证与基础信息中的 App ID。 clientSecret填写同一应用的 App Secret。 scope填写飞书侧已开通且本次登录需要的权限标识。若按上文开通了表中的三项权限,使用模板中的列表即可。 claimMapping.email模板填写 email,表示从飞书返回的email字段取登录邮箱。若企业用飞书邮箱作为登录账号,且已确认飞书返回enterprise_email,将值改为enterprise_email。 -
打开非标准 OIDC 配置页。 在目标工作空间进入管理 > 成员管理 > SSO 管理 > 用户 SSO,选择 OIDC,点击添加身份提供商。在表单右上方点击不是标准的 OIDC 配置?点击这里,切换后可看到配置文件上传。
-
上传文件并保存。
- 在连接配置中,将身份提供商名称填为「飞书」。在配置文件上传处点击上传,选择第 1 步保存的
feishu-oidc.json。 - 在登录控制中,访问限制填写允许登录的邮箱域名(如
example.com),角色授权选择员工首次登录时的工作空间角色,会话保持按企业要求设置。各字段说明见登录控制。 - 填好后点击保存。
- 在连接配置中,将身份提供商名称填为「飞书」。在配置文件上传处点击上传,选择第 1 步保存的
-
复制回填地址。 在保存成功的弹窗中复制回调 URL,供下一步填写到飞书的重定向 URL。如果要配置飞书工作台入口,再复制发起登录 URL,供下一步填写到网页应用的桌面端主页。以后可在 OIDC 列表点击该身份提供商的编辑查看这两个地址。
飞书开放平台 JSON 模板¶
飞书开放平台的 Token 接口通过请求体接收客户端凭证,用户信息位于响应的 data 层。下方模板已配置相关请求参数和接口地址。保留 getUserInfoSet.responseInfoPath 为 data,邮箱映射填写这一层内的字段名(例如 email)。
{
"scope": [
"component:user_profile",
"contact:user.email:readonly",
"contact:user.employee_id:readonly"
],
"authSet": {
"url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
"verify": true,
"paramMapping": {
"scope": "$scope",
"state": "$state",
"client_id": "$client_id",
"redirect_uri": "$redirect_uri",
"response_type": "$response_type"
}
},
"clientId": "<替换为飞书 App ID>",
"clientSecret": "<替换为飞书 App Secret>",
"modeType": "expert",
"grantType": "authorization_code",
"sslVerify": true,
"getTokenSet": {
"url": "https://open.feishu.cn/open-apis/authen/v2/oauth/token",
"method": "post",
"verify": true,
"authMethod": "none",
"paramMapping": {
"code": "$code",
"state": "$state",
"grant_type": "$grant_type",
"redirect_uri": "$redirect_uri",
"client_id": "$client_id",
"client_secret": "$client_secret"
}
},
"wellKnowURL": "",
"claimMapping": {
"email": "email",
"username": "name"
},
"getUserInfoSet": {
"url": "https://open.feishu.cn/open-apis/authen/v1/user_info",
"method": "get",
"source": "origin",
"authMethod": "bearer",
"paramMapping": {},
"responseInfoPath": "data"
},
"verifyTokenSet": {
"url": "",
"keys": [],
"method": "get",
"verify": true
}
}
飞书通过 Token 请求体中的 client_id 和 client_secret 验证应用身份。模板已在 paramMapping 中配置这两个参数,因此将 authMethod 设为 none。配置时,把飞书应用的 App ID 和 App Secret 填入 clientId 和 clientSecret。模板中以 $ 开头的值由观测云在登录时自动填充。
4. 将地址填回飞书并发布¶
- 返回飞书开发者后台的同一个应用,进入开发配置 > 安全设置。在重定向 URL中添加观测云生成的完整回调 URL,原样粘贴并保存。
- 若已添加网页应用能力,进入应用能力 > 网页应用,在网页应用配置中将桌面端主页设为观测云的发起登录 URL。如需从飞书移动端打开,也在移动端主页填入该地址。
- 点击应用发布 > 版本管理与发布 > 创建版本。在版本详情中填写版本号(如
1.0.0)和更新说明,在可用范围中加入验证账号和计划接入的成员或部门。点击保存,再点击申请线上发布。如果企业要求审批,等待管理员审核通过。版本生效后,按登录验证操作。
飞书集成平台(AnyCross)接入¶
1. 创建单点登录应用¶
- 打开飞书集成平台,点击进入飞书集成平台。在顶部使用切换功能模块进入身份集成。如入口不可用,按平台提示向企业管理员申请权限,并确认企业已开通身份集成能力。
- 在单点登录中点击新建应用,选择自建应用。填写应用名称、图标及所需的基本信息,点击下一步进入应用配置。
-
登录回调地址先留空。展开更多配置,选择 OIDC 协议,按下表配置并点击保存配置。
飞书应用配置项 填写内容 授权模式 authorization_codeScope 从 openid、profile、email开始。需要手机号且应用支持时,追加phone。返回类型 codeID Token 签名算法和加密 采用标准 OIDC 表单时,签名算法选择 HS256,对 ID Token 加密选择关闭。换取 Token 身份验证方式 新建应用可选 client_secret_basic,对应观测云标准 OIDC 表单。应用若使用client_secret_post,请选择下方的 JSON 上传方式。 -
在应用详情页的应用配置中,从应用凭证复制 App ID 和 App Secret,从 OIDC 协议端点复制服务发现地址。打开服务发现地址可查看应用支持的字段(如
claims_supported)和授权范围(如scopes_supported)。登录邮箱字段仍以员工授权后实际返回的用户信息为准。 - 切换到应用的访问授权,添加允许登录的成员或组织,确认验证账号已包含在内。
2. 在观测云添加身份提供商¶
在目标工作空间进入管理 > 成员管理 > SSO 管理 > 用户 SSO,选择 OIDC,点击添加身份提供商。按飞书应用中换取 Token 身份验证方式的实际选项配置。
方式 A:应用选择了 client_secret_basic¶
在默认的标准 OIDC 表单填写以下内容。
| 观测云字段 | 填写内容 |
|---|---|
| 身份提供商名称 | 自定义登录时展示的名称,例如「飞书」。 |
| 身份提供商 URL | 飞书应用详情中的服务发现地址。 |
| 客户端 ID | 同一应用的 App ID。 |
| 客户端密钥 | 同一应用的 App Secret。 |
| 授权请求 Scope | 选择 openid、profile、email。需要手机号且应用已支持时,增加 phone。 |
| 用户名 | 必填。填写飞书实际返回的显示名称字段,例如 name。 |
| 邮件 | 必填。填写身份提供商响应中用于登录的邮箱字段,例如 email。如果企业使用的登录邮箱由 enterprise_email 返回,则填 enterprise_email。 |
| 手机号 | 可选。只有请求了手机号且实际响应包含此字段时才填写,例如 phone_number。 |
按登录控制表填写登录控制,点击保存并复制弹窗中的回调 URL。关闭弹窗后,可在 OIDC 列表点击身份提供商的编辑重新查看。
方式 B:上传 JSON 配置(client_secret_post)¶
-
准备 JSON 文件。 复制下方AnyCross JSON 模板中的完整 JSON,保存为
feishu-anycross-oidc.json。在文件中填写或核对以下字段。JSON 字段 填写内容 clientId填写 AnyCross 应用的应用配置 > 应用凭证中的 App ID。 clientSecret填写同一应用的 App Secret。 wellKnowURL填写同一应用的应用配置 > OIDC 协议端点中的完整服务发现地址。 scope填写应用已开通且登录实际需要的授权范围。模板示例为 openid、profile、email。claimMapping模板从 email取登录邮箱,从name取用户名。若飞书使用其他字段,将映射值改为实际返回的字段名。 -
切换到非标准 OIDC。 在观测云的添加身份提供商页面,点击右上方的不是标准的 OIDC 配置?点击这里。切换后可看到配置文件上传。
- 上传文件并保存。 在连接配置中填写身份提供商名称(如「飞书」),点击配置文件上传处的上传,选择
feishu-anycross-oidc.json。按登录控制表填写访问限制、角色授权和会话保持,再点击保存。 - 复制回调 URL。 从保存成功的弹窗中复制回调 URL,供下一步填入 AnyCross 的登录回调地址。以后可在 OIDC 列表点击该身份提供商的编辑重新查看。
AnyCross JSON 模板¶
观测云会从 wellKnowURL 读取授权、Token 和用户信息接口地址,模板中的三个接口 url 因此留空。如需映射手机号,确认应用支持并已授权相应 Scope,再按实际字段补充映射,例如 "mobile": "phone_number"。
{
"scope": ["openid", "profile", "email"],
"authSet": {
"url": "",
"verify": true,
"paramMapping": {
"scope": "$scope",
"state": "$state",
"client_id": "$client_id",
"redirect_uri": "$redirect_uri",
"response_type": "$response_type"
}
},
"clientId": "<替换为 AnyCross App ID>",
"clientSecret": "<替换为 AnyCross App Secret>",
"modeType": "expert",
"grantType": "authorization_code",
"sslVerify": true,
"getTokenSet": {
"url": "",
"method": "post",
"verify": true,
"authMethod": "none",
"paramMapping": {
"code": "$code",
"state": "$state",
"grant_type": "$grant_type",
"redirect_uri": "$redirect_uri",
"client_id": "$client_id",
"client_secret": "$client_secret"
}
},
"wellKnowURL": "<替换为 AnyCross 服务发现地址>",
"claimMapping": {
"email": "email",
"username": "name"
},
"getUserInfoSet": {
"url": "",
"method": "get",
"source": "origin",
"authMethod": "bearer",
"paramMapping": {},
"responseInfoPath": ""
},
"verifyTokenSet": {
"url": "",
"keys": [],
"method": "get",
"verify": true
}
}
3. 将回调地址填回飞书并启用¶
- 回到 AnyCross,打开同一个应用,在应用配置中点击编辑。
- 在认证配置 > 登录回调地址处点击添加,原样粘贴观测云生成的完整回调 URL。
- 点击保存配置,随后点击启用。确认访问授权包含验证账号,再按登录验证操作。
观测云登录控制¶
两条接入路线均在添加身份提供商时填写下列配置。
| 字段 | 填写内容 |
|---|---|
| 访问限制 | 填写允许使用此身份提供商的员工邮箱域名,例如 example.com。多个域名用逗号分隔。域名须与登录邮箱映射返回的邮箱后缀一致。 |
| 角色授权 | 选择员工首次使用 SSO 登录时的工作空间角色,例如只读成员。如果空间配置了 OIDC 角色映射,同时核对测试成员的映射结果。 |
| 会话保持 | 根据企业要求设置无操作登录会话保持时间和登录会话最大保持时间。 |
登录验证¶
- 在目标工作空间的 OIDC 列表中确认「飞书」身份提供商已启用。
- 用浏览器无痕窗口打开当前站点的登录页,点击单点登录。中国区主站可直接打开 SSO 登录页。
- 输入验证账号的完整企业邮箱(例如
alice@example.com),点击获取登录地址。选择已配置的飞书身份提供商,点击认证/登录。 - 在飞书完成认证和授权。跳回观测云后,选择目标工作空间,确认进入的是预期账号和工作空间,并核对该账号获得的角色。
- 若飞书开放平台已配置工作台入口,再在飞书工作台中打开已发布的应用,验证从飞书发起登录的流程。
常见问题与排查¶
| 现象 | 检查方法 |
|---|---|
飞书提示回调地址不合法(20029 或 redirect_uri 错误) |
从 OIDC 身份提供商的编辑页重新复制回调 URL。在开放平台检查安全设置 > 重定向 URL,在 AnyCross 检查应用配置 > 认证配置 > 登录回调地址。核对完整地址,包括协议、域名、路径和末尾斜杠。确认改动已发布或已保存并启用。 |
| 提示未找到 SSO 账户邮箱 | 开放平台模板从 data 层读取邮箱,AnyCross 模板默认从响应顶层读取。检查 claimMapping.email 指向的字段是否存在且包含有效邮箱。若返回 email,映射填写 email;若实际返回 enterprise_email 且该邮箱才是所需账号,映射填写 enterprise_email。若两个字段均为空,检查员工邮箱资料、应用权限、授权范围和版本生效状态。需要协助时,可向观测云支持提供报错页的 Trace ID,以便定位返回字段。 |
| 提示权限不足或 Scope 有误 | 检查 OIDC 表单或 JSON 中请求的 Scope 是否已在飞书侧开通并生效。确认员工已纳入开放平台应用的可用范围和相关数据权限,或已获得 AnyCross 应用的访问授权。 |
| 无法换取 Token | 核对 App ID、App Secret 来自同一应用。AnyCross 还需核对换取 Token 身份验证方式与在观测云选择的配置方式一致。 |
| 输入邮箱后找不到飞书登录入口,或认证成功后看不到目标空间 | 检查工作空间的身份提供商是否已启用、首次登录邮箱是否匹配访问限制、员工是否绑定过其他身份提供商,以及登录后的工作空间角色。具体匹配规则见 SSO 管理的用户登录说明。 |
如需查看飞书两类应用后台的逐步截图,可参阅 观测云集成飞书 SSO 最佳实践。