自定义登录认证

本文用于说明如何将支持 OAuth 2.0 或 OpenID Connect（OIDC）的身份提供方配置为 DuMate 管理平台的自定义登录认证源。配置完成后，用户可在 DuMate 登录页选择对应认证源，并使用企业现有账号完成登录。

适用范围

自定义认证源适用于支持 OAuth 2.0 授权码模式的身份提供方。身份提供方需要提供以下能力：

• 创建 OAuth 2.0 或 OIDC 应用，并提供 Client ID 和 Client Secret
• 提供授权端点、Token 端点和用户信息端点
• 支持配置登录回调链接
• 授权成功后通过回调链接返回 code
• Token 端点能够使用 code 换取 access_token
• 用户信息端点能够使用 Bearer Token 返回用户唯一标识和姓名等信息

说明：OIDC 是 OAuth 2.0 的身份认证扩展。管理员只需在 DuMate 中配置身份提供方提供的端点、凭证和用户映射，登录过程由 DuMate 与身份提供方完成。

在身份提供方创建应用

不同身份提供方的页面名称可能不同，请以对应平台的操作说明为准。

1. 登录身份提供方的管理平台，创建 OAuth 2.0 或 OIDC 应用。
2. 应用类型选择 Web 应用，授权模式选择 Authorization Code。
3. 记录应用生成的 Client ID 和 Client Secret。
4. 根据登录所需的用户信息申请 Scope。OIDC 场景通常需要包含 openid，并按需申请用户姓名、邮箱等信息的访问权限。
5. 保留应用的回调地址或重定向 URI 配置页面，稍后填入 DuMate 生成的回调链接。

说明：如果身份提供方支持 OIDC Discovery，可访问其 /.well-known/openid-configuration 地址，并从返回内容中查找 authorization_endpoint、token_endpoint 和 userinfo_endpoint。

进入登录认证

管理员登录 DuMate 管理平台后，依次进入企业设置 -> 登录认证。

点击添加认证源，进入认证源配置页面。

页面支持搜索认证源，并对已创建的认证源执行启用、禁用、编辑、删除等操作。

注意：认证源处于启用状态时，对应登录入口会显示在 DuMate 登录页；处于禁用状态时，登录入口不会显示，但认证源配置仍会保留。

添加自定义认证源

在认证源配置页面，将认证源选择为自定义。

按照以下说明填写配置：

说明：授权端点、Token 端点和用户信息端点必须填写完整 URL，并建议使用 HTTPS。不同环境的端点和客户端凭证通常不能混用。

完成必填信息和用户映射后，点击确定保存认证源。

配置用户映射

用户映射用于将身份提供方返回的用户信息绑定到 DuMate 用户。左侧填写用户信息端点返回的字段名称，右侧为对应的 DuMate 用户字段。

例如，用户信息端点返回以下内容：

1{
2  "sub": "zhangsan",
3  "name": "张三",
4  "email": "zhangsan@example.com"
5}

可按以下方式配置：

• 登录用户名对应的身份认证源字段必须稳定、唯一且不为空。
• OIDC 标准字段 sub 表示用户在身份提供方中的唯一标识，适合作为新用户的登录用户名。
• 如果需要关联 DuMate 中的已有用户，身份提供方返回的字段值必须与已有用户的登录用户名一致。例如已有用户以邮箱作为登录用户名时，可将唯一的邮箱字段映射到登录用户名。
• 字段名称应与用户信息接口返回结果保持一致，包括大小写。

说明：正式启用前，建议先使用测试账号检查用户信息接口的实际返回结果，并验证映射后是否关联到预期的 DuMate 用户。

配置回调链接

按以下步骤配置回调链接：

1. 在配置信息中找到回调链接，复制 DuMate 生成的完整地址。

2. 返回身份提供方的应用配置页面，找到回调地址、重定向 URI 或 Redirect URI 配置，添加 DuMate 生成的回调链接。

确保身份提供方中的链接与 DuMate 展示的链接完全一致，包括协议、域名、路径和参数。保存配置，并按身份提供方要求发布或启用应用。

启用认证源

身份提供方应用配置完成后，回到 DuMate 管理平台的企业设置 -> 登录认证页面，确认认证源状态为启用。

登录验证

启用后，可按以下步骤验证：

1. 打开 DuMate 登录页，选择企业员工登录，输入企业标识。

2. 选择自定义登录。

3. 进入 DuMate 的账号登录页面，输入企业账号的用户名和密码，点击登录。

登录成功后，确认是否能够正常进入 DuMate，并检查用户映射、姓名和席位分配是否符合预期。

常见问题

Q：登录页看不到自定义认证源

A：检查认证源是否已保存并处于启用状态。认证源处于禁用状态时，对应选项不会显示在 DuMate 登录页。

Q：身份提供方提示回调地址不合法

A：检查身份提供方配置的回调地址是否与 DuMate 展示的回调链接完全一致，尤其注意协议、域名、路径、参数和末尾斜杠。

Q：提示客户端 ID 或客户端密钥错误

A：确认 Client ID 和 Client Secret 来自同一个应用和同一个环境，并检查客户端密钥是否已失效或重新生成。

Q：授权后无法换取 Token

A：检查 Token 端点是否正确、应用是否支持Authorization Code模式，以及身份提供方是否已启用该应用。授权端点和 Token 端点必须属于同一环境。

Q：无法获取用户信息

A：检查用户信息端点和 Scope 是否正确，并确认身份提供方允许使用Bearer Token调用用户信息接口。用户信息接口应返回 JSON 格式的用户信息。

Q：授权成功但无法登录 DuMate

A：优先检查以下项：

• 用户映射字段是否与用户信息接口返回字段一致
• 登录用户名对应字段是否存在、唯一且不为空
• 已有用户的登录用户名是否与映射字段值一致
• 是否有可用席位，以及自动分配席位配置是否符合预期