飞书与观测云（SaaS）OIDC 配置说明¶
本文档包含两部分：
- 飞书集成平台（Anycross）与观测云对接说明；
- 飞书原生平台与观测云对接说明。
根据应用在飞书侧的创建方式不同，请选用对应章节的配置步骤与 JSON 模板。
一、飞书集成平台（Anycross）接入说明¶
适用场景¶
适用于通过飞书集成平台（https://anycross.feishu.cn）创建的应用与观测云（SaaS）通过 OIDC 实现 SSO 对接。
核心规则¶
- 若飞书应用的 Token 认证方式为
client_secret_basic：可在观测云 UI 直接填写clientId/clientSecret，无需导入 JSON 模板（推荐）。 - 若 Token 认证方式为
client_secret_post：需在观测云「非 OIDC 标准配置」中导入 JSON 模板。
客户需准备的信息¶
| 信息项 | 说明 |
|---|---|
| clientId | 应用的客户端 ID（App ID） |
| clientSecret | 应用的客户端密钥（App Secret） |
| scope | 模板默认权限（无需修改） |
| claimMapping | 账号信息映射（固定） |
固定的 claimMapping：
{
"email": "enterprise_email",
"mobile": "mobile",
"username": "email",
"exterId": "enterprise_email"
}
说明：飞书 OIDC 返回的 enterprise_email 为企业邮箱，通常必存在且唯一，建议将观测云的 email 映射为该字段。
飞书集成平台端检查项¶
- 确认 App ID、App Secret 有效。
- 获取服务发现地址（服务发现 URL，模板字段为
wellKnowURL）。 - 授权模式应为
authorization_code；Scope 包含openid、profile、email、phone、offline_access。 - 确认换取 Token 的验证方式（
client_secret_basic或client_secret_post）。
观测云端配置¶
场景 1 — client_secret_basic（推荐）
- 登录观测云，进入 SSO 配置 → OIDC 页面，填写服务发现地址、
clientId和clientSecret。 - 保存并测试 SSO 登录。
场景 2 — client_secret_post
- 参考观测云官方「OIDC 非标准配置」章节，使用下方 JSON 模板填充
clientId、clientSecret、wellKnowURL。 - 在观测云的 OIDC 非标准配置页面导入该 JSON 模板并保存，测试 SSO 登录。
JSON 模板（仅用于 client_secret_post 场景）¶
{
"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": "<填写 App ID>",
"clientSecret": "<填写 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": "<填写飞书服务发现地址>",
"claimMapping": {
"email": "enterprise_email",
"mobile": "mobile",
"username": "email",
"exterId": "enterprise_email"
},
"getUserInfoSet": {
"url": "",
"method": "get",
"source": "origin",
"authMethod": "bearer",
"paramMapping": {},
"responseInfoPath": ""
},
"verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}
模板填充说明：仅修改 clientId、clientSecret、wellKnowURL；其余字段保持默认（所有 url 字段留空，服务发现地址会自动识别接口）。
二、飞书原生平台接入说明¶
适用于在飞书原生平台创建的应用与观测云（SaaS）通过 OIDC 对接的场景。请勿将本节与“集成平台”配置混用。
不兼容点与适配原因¶
- 飞书原生平台在 Code 换取 Token 时不支持 Basic 认证，仅支持
client_secret_post（通过 POST body 传参）。 - 飞书返回的用户信息包含
data嵌套层，需在模板中通过responseInfoPath指定为data。
客户需准备的信息¶
| 信息项 | 说明 |
|---|---|
| clientId | App ID |
| clientSecret | App Secret |
| scope | 固定权限列表，需与飞书侧实际开通权限一致 |
| claimMapping | 账号映射（固定） |
固定 claimMapping：
{
"email": "enterprise_email",
"mobile": "mobile",
"username": "email",
"exterId": "enterprise_email"
}
固定 scope 列表示例（务必与飞书实际开通权限一致）：
飞书端检查项¶
- 确认
client_id（App ID）和client_secret（App Secret）正确。 - 在权限管理中确认已开通模板中列出的
scope权限并已发布应用。 - 预留回调地址：观测云会生成回调地址，需将该地址配置到飞书应用的回调地址中并发布。
观测云端配置与回调设置¶
- 在观测云 OIDC 非标准配置页面使用下方模板，仅替换
clientId和clientSecret，保持其他字段不变。 - 确认
getUserInfoSet.responseInfoPath为data（适配飞书返回结构）。 - 导入模板并保存，复制观测云生成的回调地址，填写到飞书应用开发配置 → 回调地址，发布应用。
- 测试 SSO 登录。
JSON 模板（飞书原生平台专用）¶
{
"scope": [
"component:user_profile",
"contact:user.employee_id:readonly",
"contact:user.email: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": "enterprise_email",
"mobile": "mobile",
"username": "email",
"exterId": "enterprise_email"
},
"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}
}
模板说明：仅修改 clientId、clientSecret；其他字段为飞书官方固定配置，不要改动。
常见问题与排查¶
问题 1：回调地址不合法（错误码：20029）¶
现象：SSO 登录时提示 redirect_uri 不合法。
解决：从观测云 SSO 配置页复制系统生成的回调地址（不要手动更改），粘贴到飞书应用的回调地址配置并发布，然后在观测云刷新配置后重试。
问题 2：认证失败（提示：未找到 sso 账户邮箱）¶
现象：登录时报错未找到 SSO 账户邮箱。
解决：查看飞书返回的用户信息（通过报错中的 trace_id），确认 getUserInfoSet.responseInfoPath 的配置：
- 若用户信息在
data嵌套层，保持responseInfoPath = "data"； - 若返回为扁平结构，设置
responseInfoPath = ""（空字符串）。
修改后重新导入模板并测试。
问题 3：权限不足（Scope 配置异常）¶
解决：确认飞书应用已开通模板中列出的 scope 权限并已发布；确保 JSON 模板中的 scope 列表与飞书侧完全一致，重新导入并保存。