飞书与观测云（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	账号信息映射，需与实际 userinfo 字段匹配

claimMapping 示例：

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email"
}

说明：模板将登录邮箱映射为 enterprise_email。请确认应用有权获取该字段，且目标用户的实际 userinfo 中返回了有效邮箱；不能假设该字段一定存在。若采用其它邮箱字段，应先确认它符合账号身份要求，再调整 claimMapping.email。

当前登录会读取 email、name、username 和 mobile 映射，其中有效邮箱是必需的。exterId 映射不参与此登录流程，模板无需填写。

飞书集成平台端检查项¶

确认 App ID、App Secret 有效。
获取服务发现地址（服务发现 URL，模板字段为 wellKnowURL）。
授权模式应为 authorization_code。模板以 openid、profile、email 为起点，请按服务发现信息及实际开通权限核对。
若需要手机号或离线授权，先确认应用支持并获准请求对应的 phone、offline_access scope，再按需加入模板；不要将这两个 scope 作为所有登录场景的必填项。
确认换取 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"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

模板填充说明：填写 clientId、clientSecret、wellKnowURL，并核对 scope 与 claimMapping。各接口的 url 字段留空时，由服务发现信息识别接口地址。

二、飞书原生平台接入说明¶

适用于在飞书原生平台创建的应用与观测云（SaaS）通过 OIDC 对接的场景。请勿将本节与“集成平台”配置混用。

不兼容点与适配原因¶

飞书原生平台在 Code 换取 Token 时不支持 Basic 认证，仅支持 client_secret_post（通过 POST body 传参）。
飞书返回的用户信息包含 data 嵌套层，需在模板中通过 responseInfoPath 指定为 data。

客户需准备的信息¶

信息项	说明
clientId	App ID
clientSecret	App Secret
scope	权限列表示例，需与飞书侧实际开通权限及实际用途匹配
claimMapping	账号映射，需与实际 userinfo 字段匹配

claimMapping 示例：

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email"
}

scope 列表示例（务必与飞书实际开通权限一致）：

["component:user_profile","contact:user.employee_id:readonly","contact:user.email:readonly"]

飞书端检查项¶

确认 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"
  },
  "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 后，核对 scope 及实际返回的 claimMapping.email 字段。getTokenSet 通过 POST body 发送客户端凭据，responseInfoPath=data 用于提取用户信息；应与所接入接口的协议和响应结构保持一致。

常见问题与排查¶

问题 1：回调地址不合法（错误码：20029）¶

现象：SSO 登录时提示 redirect_uri 不合法。

解决：从观测云 SSO 配置页复制系统生成的回调地址（不要手动更改），粘贴到飞书应用的回调地址配置并发布，然后在观测云刷新配置后重试。

问题 2：认证失败（提示：未找到 sso 账户邮箱）¶

现象：登录时报错未找到 SSO 账户邮箱。

解决：查看飞书返回的用户信息（通过报错中的 trace_id），确认 getUserInfoSet.responseInfoPath 的配置：

若用户信息在 data 嵌套层，保持 responseInfoPath = "data"；
若返回为扁平结构，设置 responseInfoPath = ""（空字符串）；
确认取出该层后，claimMapping.email 指向的字段确实存在且为有效邮箱；
若邮箱字段未返回，检查应用权限、用户授权及用户邮箱信息。只修改 responseInfoPath 不能解决邮箱字段缺失。

修改后重新导入模板并测试。

问题 3：权限不足（Scope 配置异常）¶

解决：确认飞书应用已开通模板中列出的 scope 权限并已发布；确保 JSON 模板中的 scope 列表与飞书侧完全一致，重新导入并保存。

飞书与观测云（SaaS）OIDC 配置说明¶

一、飞书集成平台（Anycross）接入说明¶

适用场景¶

核心规则¶

客户需准备的信息¶

飞书集成平台端检查项¶

观测云端配置¶

JSON 模板（仅用于 client_secret_post 场景）¶

二、飞书原生平台接入说明¶

不兼容点与适配原因¶

客户需准备的信息¶

飞书端检查项¶

观测云端配置与回调设置¶

JSON 模板（飞书原生平台专用）¶

常见问题与排查¶

问题 1：回调地址不合法（错误码：20029）¶

问题 2：认证失败（提示：未找到 sso 账户邮箱）¶

问题 3：权限不足（Scope 配置异常）¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？