本指南旨在帮助管理员解决下游业务系统（作为服务提供者 SP）通过飞连（作为身份提供者 IdP）进行 OIDC 集成时遇到的各类异常场景（如：登录跳转失败、认证报错、登录后无法获取用户信息等）。借助本文中的排查方法，管理员可快速定位问题并解决两端配置不一致等核心问题。

适用问题 #

• 链路跳转类：在业务系统点击“OIDC 登录”无法跳转至飞连，或跳转地址异常。
• 认证解析类：跳转至飞连后立即报错（如 invalid_request、参数错误、无效的授权范围）。
• Token 获取类：飞连认证成功并回跳业务系统后，业务系统无法通过 Code 换取 Token，或提示授权码无效。
• 属性缺失类：登录业务系统后，无法正确获取用户名、工号等关键信息。

相关术语说明 #

背景知识：OIDC SSO 登录流程 #

在与企业进行用户 SSO 集成时，飞连作为身份提供者（IdP），企业自有的业务系统则作为服务提供者（SP）。通过 IdP 颁发的 ID Token，下游应用提供者能够确定自身用户与飞连用户的对应关系，从而实现免密访问。
标准登录交互过程如下：

具体排查步骤 #

阶段一：常见配置项检查 #

多数单点登录失败问题由基础配置不一致引起，请优先排查以下配置：

1. 回调地址（Redirect URI）一致性
   • 下游业务系统在发起请求时传递的 redirect_uri，必须与飞连管理后台配置的回调地址完全一致（包括协议、域名、路径及参数）。
   • 在调用“认证登录接口（/api/oidc/authorize）”和“获取 Token 接口（/api/oidc/token）”时，两者传递的 redirect_uri 参数也必须保持完全一致。
2. Token 获取与使用限制
   • Refresh Token 机制：如果使用 refresh_token 获取了新的 access_token，那么之前获取的旧 access_token 会立即过期失效，无法继续使用。
   • ID Token 内容：id_token 为固定生成的 JWT 格式，内部包含的信息（Claim）不可自定义。如需获取用户的额外字段信息，业务系统需通过 access_token 调用 UserInfo 接口获取。

阶段二：接口连通性手动验证 #

如果基础配置检查无误，建议通过手动模拟请求的方式，验证飞连侧的 OIDC 接口功能是否正常。

1. 构造请求获取 Authorization Code
   此请求必须通过浏览器访问。
   为了避免获取到的 Code 自动回传到真实的业务服务器而被消费，建议在测试前修改本机 hosts 文件，将回调域名指向一个不存在的 IP。
   在浏览器地址栏（或开启 F12 开发者工具）访问以下链接获取 Code：

   https://{飞连门户域名}:{飞连门户端口}/api/oidc/authorize?client_id={飞连管理后台获取的client_id}&redirect_uri={管理后台配置的回调地址}&response_type=code&scope=openid
   

提示：请替换上述 URL 中的 {飞连门户域名}、{飞连门户端口}、{client_id} 及 {回调地址} 为实际目标值。

2. 使用 Code 换取 Token
   获取到 Code 后，请使用以下 cURL 命令（或使用 Postman 等工具）换取 Token。
   注意：Code 是一次性的，且有效期较短，请尽快完成此步。

   curl --location 'https://{飞连门户域名}:{飞连门户端口}/api/oidc/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id={飞连管理后台获取的client_id}' \
   --data-urlencode 'client_secret={飞连管理后台获取的client_secret}' \
   --data-urlencode 'code={步骤1中获取的code}' \
   --data-urlencode 'redirect_uri={管理后台配置的回调地址}' \
   --data-urlencode 'grant_type=authorization_code'
   

   期望的返回结果示例：

   {
     "access_token": "<Access_Token字符串>",
     "refresh_token": "<Refresh_Token字符串>",
     "token_type": "bearer",
     "id_token": "<ID_Token字符串>",
     "expires_in": 7200
   }
   

3. 使用 Access Token 换取用户信息
   使用上一步获取的 access_token，调用 UserInfo 接口验证能否成功获取用户信息：

   curl -k 'https://{飞连门户域名}:{飞连门户端口}/api/oidc/userinfo/normal?access_token={上一步获取的access_token}'
   

排障结论：

• 如果上述手动验证步骤均能正常返回 Token 和用户信息，说明飞连侧的 OIDC 接口功能正常。此时需业务侧排查其代码实现或网络调用情况。
• 如果在某一步报错，请根据接口返回的错误码（详见附录）或联系技术支持进行定位。

阶段三：收集日志并联系技术支持 #

若通过以上步骤仍无法准确定位问题，请收集以下材料联系技术支持协助排查：

1. 故障现象截图：包含浏览器地址栏的完整报错页面、报错提示，以及复现问题的详细步骤。
2. 配置对照图：飞连管理后台 OIDC 配置页截图 + 业务系统 OIDC 配置页截图。
3. HAR 日志：
   • 开启浏览器开发者工具（F12）。
   • 切换到 Network（网络）​面板，勾选 Preserve log（保留日志）​和 Disable cache（停用缓存）。
   • 尝试复现问题，复现后将网络请求列表导出为 .har 文件。
     
4. 飞连侧服务日志：
   • 登录飞连服务器，获取核心日志：/opt/corplink/log/portal.*.log
   • 或登录飞连运维平台：集群管理 > 服务列表 > 用户门户 > 查看详情 > 服务日志，下载 portal.*.log。

附录 #

1. ID Token 解析 #

ID Token 解码后包含以下关键声明（Claim）：

2. 接口列表及参数规范 #

2.1 认证登录接口

用户未登录或需要判断用户是否登录时，让用户浏览器重定向到此地址。

• PATH：/api/oidc/authorize
• Method：GET

2.2 获取 Token 接口（包含 Refresh）

使用 Code 换取 Token，请求必须是 x-www-form-urlencoded 表单形式。

• PATH：/api/oidc/token
• Method：POST

常见错误码（Failure Code）：

2.3 获取用户信息接口

使用 Access Token 获取对应用户的详细信息。

• PATH：/api/oidc/userinfo/normal
• Method：GET

2.4 发起登出接口

发起 OIDC 登出请求，清理当前浏览器的 OIDC 登录态。必须由浏览器发起，不支持服务间调用。

• PATH：/api/oidc/logout
• Method：GET / POST

2.5 单点登出 API（飞连主动发送）

用户登出时，飞连会主动向配置了登出 URL 的已登录应用发送单点登出请求（Back-Channel Logout）。应用收到后需执行注销流程并返回 200 状态码。

POST /backchannel_logout HTTP/1.1
Host: rp.example.org
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ...

其中 logout_token 解码后的 JSON 结构如下，业务系统需校验其中的 sub 等字段以确认登出用户：

{ 
  "iss": "https://corplink.com",
  "sub": "1",
  "aud": "LzcRGdpLxwhzGXQFbufPZZKFXkcwfXhnicuFhFmf",
  "iat": 1644204668,
  "jti": "ID.c05266e3369d4dee9ae01a629c4c7595",
  "nbf": 1644204668,
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {} 
  } 
}