认证源-OIDC协议

概述

OpenID Connect（OIDC）是基于 OAuth 2.0 协议之上的现代身份认证层，允许客户端通过授权服务器验证用户身份并获取用户基本信息。专属集成平台支持将符合 OIDC 标准的第三方身份提供方（IdP）配置为认证源，实现单点登录（SSO）与用户信息同步。

OIDC 认证源适用于已部署 OIDC 兼容 IdP（如 Keycloak、Okta、Auth0）的组织，通过标准化的 JWT ID Token 和 UserInfo Endpoint 完成用户身份验证与属性交换。

前提条件

序号	条件	说明
1	拥有 OIDC 身份提供方	已部署支持 OIDC 协议的身份提供方，如 Keycloak、Okta、Auth0 等
2	Issuer URL	OIDC 提供方的 Issuer 地址，通常以 `/.well-known/openid-configuration` 结尾的路径可被自动发现
3	Client ID	在 IdP 中注册应用后获得的客户端标识
4	Client Secret	在 IdP 中注册应用后获得的客户端密钥
5	回调地址	专属集成平台的回调地址，格式为 `{平台域名}/api/auth/callback/oidc`
6	网络可达	专属集成平台能够访问 IdP 的 OIDC Discovery 端点、授权端点、Token 端点和 UserInfo 端点

操作步骤

添加 OIDC 认证源

添加认证源

登录专属集成平台管理后台。

在左侧导航栏依次点击 用户中心 → 认证源管理。

点击页面右上角的 添加认证源 按钮。

在弹出的选择框中，选择 OIDC 协议 类型。

提示：如果页面上已有其他认证源，新增的认证源将出现在列表末尾。你可以通过拖拽调整认证源在登录页的显示顺序。

配置基本信息

在认证源配置表单中填写以下参数：

参数	必填	说明	示例
认证源名称	是	在登录页显示的认证源名称，建议使用 IdP 品牌名	`公司SSO`
Issuer URL	是	OIDC 提供方的发行者地址，平台将自动通过 `/.well-known/openid-configuration` 发现端点	`https://idp.example.com/realms/master`
Client ID	是	IdP 中注册的客户端 ID	`my-client-id`
Client Secret	是	IdP 中注册的客户端密钥	`********`
Scopes	是	请求的授权范围，多个以空格分隔	`openid profile email`
认证源图标	否	上传图标文件，支持 PNG/JPG，建议 64×64px	—

重要：Issuer URL 必须以 https:// 开头，平台将自动拼接 /.well-known/openid-configuration 路径进行服务发现。若 IdP 不标准支持该路径，请联系管理员。

注意：Scopes 中必须包含 openid，否则将无法获取 ID Token。如需获取用户邮箱和姓名，请附加 profile 和 email。

配置回调地址

复制专属集成平台自动生成的回调地址（格式：{平台域名}/api/auth/callback/oidc）。

在 Redirect URI 或 回调地址 配置项中，粘贴上一步复制的地址。

保存 IdP 端配置。

警告：回调地址必须在 IdP 端精确匹配，包括协议、域名、端口和路径。任何不一致都会导致授权后跳转失败，浏览器将显示 redirect_uri_mismatch 错误。

配置属性映射

将 IdP 返回的用户属性映射到平台用户模型：

IdP 属性（claim）	平台字段	必填	说明
`sub`	`username`	是	用户在 IdP 中的唯一标识，映射为平台登录用户名
`email`	`email`	是	用户邮箱地址
`name`	`display_name`	是	用户显示名称，用于界面展示
`preferred_username`	`nickname`	否	用户昵称
`phone_number`	`phone`	否	用户手机号
`picture`	`avatar`	否	用户头像 URL

提示：属性映射的 key 名称需与 IdP 实际返回的 claim 名称保持一致。可在 IdP 管理后台查看 ID Token 或 UserInfo 端点返回的标准 claims。

配置 JIT

JIT（Just-In-Time）指用户首次通过该认证源登录时，平台自动创建用户账号的功能。

参数	说明
启用 JIT	开启后，首次通过该认证源认证的用户将自动在平台创建账号
默认角色	新创建用户自动分配的角色
默认组织	新创建用户自动归属的组织

重要：建议开启 JIT 并提供默认角色与组织，否则未在平台预创建的用户将无法登录。若关闭 JIT，需在平台预先创建对应用户账号后方可认证。

完成配置

确认所有参数填写无误。

点击保存按钮。

系统将自动验证 OIDC Discovery 端点连通性，验证通过后认证源创建成功。

认证源将出现在列表中，状态为 已启用。

提示：创建后可随时点击认证源对应行的编辑或禁用按钮进行修改。修改后用户下次登录时生效。

验证与测试

测试项	验证方法	预期结果
认证源连通性	在认证源列表中点击测试连接	提示连接成功
登录跳转	打开登录页，点击该认证源图标	正确跳转至 IdP 登录页面
用户认证	在 IdP 页面输入有效凭据	成功跳回平台并完成登录
属性映射	登录后查看用户中心个人信息	用户名、邮箱、显示名称与 IdP 一致
JIT 创建	使用 IdP 中未预先创建的新用户登录	平台自动创建该用户账号
Token 刷新	登录后持续操作超过 access_token 有效期	系统静默刷新 token，无明显中断

常见问题

Q1：提示"无法获取 OIDC Discovery 配置"，如何排查？

Q2：登录后回调显示 redirect_uri_mismatch 错误？

Q3：用户登录后用户名显示为随机字符串或不完整？

Q4：Scopes 中已配置 profile 和 email，但 UserInfo 仍无对应字段？

概述#

前提条件#

操作步骤#

添加 OIDC 认证源#

验证与测试#

常见问题#

概述

前提条件

操作步骤

添加 OIDC 认证源

验证与测试

常见问题