单点登录

Version 25.2.9314


单点登录


知行之桥支持通过 OpenID Connect 和 SAML 2.0 标准进行单点登录 (SSO)。可以使用实现这些标准的身份提供商 (IdP) 作为知行之桥的 SSO 平台。IdP 包括 Entra ID(以前称为 Azure AD)和 Okta 等工具。

概述

启用 SSO 需要在应用程序 系统设置 页面的 单点登录 选项卡上配置一组设置。每个设置均在以下 SSO 设置 中说明。还可以从 SSO 提供商 导入设置

配置 SSO 设置后,应为知行之桥中创建的用户提供联合标识(Federation ID)。该联合ID将知行之桥用户名与身份提供者(IdP)实体联系在一起。当知行之桥用户尝试登录应用程序时,它将被重定向到 SSO 平台,并要求必须在 SSO 平台中输入相应身份的凭据。

一旦配置了 SSO 并且知行之桥用户有一个联合ID来将他们与身份提供者(IdP)相关联后,任何进一步的 SSO 用户管理高级配置都应该在 SSO 平台本身中进行。

如果启用了即时 (JIT) 配置功能,系统会在用户登录时根据从身份提供商 (IdP) 收到的属性(例如,用户的姓名和电子邮件地址)自动在知行之桥中创建一个新用户帐户。此身份和访问管理 (IAM) 流程简化了用户入职流程,无需手动创建帐户。当用户首次通过身份提供商 (IdP) 访问知行之桥时,即时预配功能尤为有用,应用程序会收到一条确认其身份的安全消息。生成的帐户将被分配一个默认角色,具体角色在单点登录 (SSO) 设置中指定。

注意:知行之桥目前仅支持个人用户,不支持用户组。 如果 SSO 平台为一组用户提供访问权限,则必须将该组中的每个用户添加为 知行之桥Users 选项卡上的用户 设置页面以便登录。 每个用户应引用来自身份提供商(IdP)的联合 ID(如下所述)。

SSO 设置

本节介绍知行之桥中的各项 SSO 设置及其含义。这些设置的详细信息可能因身份提供商(IdP)而异。Entra ID 指南可供参考。

OpenID Connect 设置

  • 回调 URL 回调 URL 在 IdP(而非 知行之桥)中配置,用于指示用户在 IdP 上执行身份验证后应返回的位置。有关更多信息,请参阅回调 URL
  • OAuth 客户端 ID 与 IdP 中创建的 OAuth 应用程序关联的客户端 ID。
  • OAuth 客户端密钥 与 IdP 中创建的 OAuth 应用程序关联的客户端密钥。
  • 令牌接收者(Audience URIs) SSO 登录令牌的预期接收者。这可确保 SSO 平台生成的令牌仅供 知行之桥 使用。将此值设置为标识 知行之桥 在您的 SSO 平台中为受信任应用程序的 URI(例如,SSO 平台为 知行之桥 生成的应用程序 ID)。要容纳多个 URI,请提供以逗号分隔的列表。
  • 发现 URL 从 SSO 提供商 导入设置 时必需。
  • 令牌颁发者证书 IdP 用于签署 JWT 令牌的证书的公共部分。这有助于确保只接受由预期 IdP 生成的令牌。
  • 令牌颁发者标识符(Issuer Identifier) IdP 在生成 JWT 令牌时使用的标识符。知行之桥 会验证令牌以确保其包含此标识符。这有助于确保只接受由预期 IdP 生成的令牌。
  • 授权 URL 用户应通过 IdP 执行授权的 URL。当 SSO 用户尝试登录 知行之桥 时,应用程序会将用户重定向到此 URL,用户可在其中输入其 SSO 平台凭据。
  • 令牌 URL 可从 IdP 获取安全身份验证令牌的 URL。用户通过
  • 注销 URL 指定 知行之桥 用户注销应用程序后重定向到的位置。
  • 默认范围(Scope) 以空格分隔的范围列表(权限集),用于向 IdP 请求。通常,范围至少应包含 profile openid 以请求身份验证。
  • 登录用户的 ID 字段 来自 IdP 的值,用作联合ID。换句话说,这指定在将用户从 IdP 映射到 知行之桥 用户名时用作联合ID 的声明。有关更多信息,请参阅联合标识(Federation ID)和登录用户的 ID 字段(Key Claim)设置
  • 签名算法 签名的 JWT 令牌接受哪些签名算法。未签名的令牌永远不会被接受。
  • 即时 (JIT) 配置 用户首次登录时,是否在 知行之桥 中自动创建新用户帐户。用户详细信息基于声明中提供的属性。
  • 默认角色 分配给 JIT 配置期间创建的帐户的 角色(支持、标准或管理员)。如果您选择 无默认角色,则使用声明中指定的角色。

SAML 2.0 设置

  • 断言消费者服务 (ACS) URL 用户成功登录后,IdP 发送 SAML 身份验证响应的 知行之桥 应用程序端点。这类似于 OpenID 中的 回调 URL 设置。
  • 令牌接收者(Audience URIs) SAML 断言所针对的唯一标识符(通常是应用程序的实体 ID)。用于验证响应是否适用于您的应用程序。
  • SAML 发现 URL 用于确定应使用哪个 IdP 进行身份验证的端点。从您的 SSO 提供商导入设置 时必需。
  • 令牌颁发者证书 IdP 用于签署 JWT 令牌的证书的公共部分。有助于确保只接受由预期 IdP 生成的令牌。
  • 实体 ID 用于在 SAML 身份验证过程中标识 IdP 或服务提供商的全局唯一标识符(通常格式化为 URI)。
  • 单点登录 URL 服务提供商将用户重定向到的 IdP 端点,以启动 SAML 身份验证流程。
  • 注销 URL 指定 知行之桥 用户退出应用程序后重定向到的位置。
  • 即时 (JIT) 配置 用户首次登录时是否在 知行之桥 中自动创建新用户帐户。用户详细信息基于 SAML 断言中提供的属性。
  • 默认角色 分配给 JIT 配置期间创建的帐户的 角色(支持、标准或管理员)。如果您选择 无默认角色,则使用 SAML 断言中指定的角色。

联合标识(Federation ID)和登录用户的 ID 字段(Key Claim)设置

当知行之桥用户通过身份提供者(IdP)登录时,知行之桥会将该本地用户的联合 ID 与提供商的身份声明进行比较。 Key Claim 指定知行之桥应用于此比较的身份提供商的值。

我们建议将 ID 字段(Key Claim)设置为身份提供者(IdP)中每个用户独有的值,例如 oid。在这种情况下,可以通过在需要访问 Arc 的身份提供者中查找分配给用户的 oid 值来获取联合 ID 值。

导入设置

如果拥有 OpenID 发现 URLSAML 发现 URL,则可以点击 导入设置 按钮从 SSO 提供商导入设置。这将为 令牌颁发者证书令牌 URL 等设置提供值。使用此功能时,颁发者证书会定期自动刷新,以确保在 SSO 提供商轮换这些证书时,应用程序不会锁定用户。

Entra ID(Azure AD)配置

本节解释了当 Entra ID 用作 OpenID IdP 时上述每个设置的可能值。

  • 回调 URL 将此设置为用户通过 IdP 进行身份验证后应转到的 URL。
  • OAuth 客户端 ID 此值由 Entra ID 在平台中创建 OAuth 应用程序后分配。
  • OAuth 客户端密钥 此值由 Entra ID 在平台中创建 OAuth 应用程序后分配。
  • 令牌接收者(Audience URIs) 只需一个 URI,即 Entra ID 为知行之桥分配的应用程序 ID(客户端 ID)。
  • 令牌颁发者证书 Entra ID 可能使用的公共证书可在此处 找到。
  • 令牌颁发者标识符 使用下面描述的 Entra ID 元数据文档 查找此值。
  • 授权 URL 此 URL 是 Entra ID 中“端点”列表中的“OAuth 2.0 授权端点 (v2)”。
  • 令牌 URL 使用下述 Entra ID 元数据文档查找此值。
  • 注销 URL 将此 URL 设置为用户注销后应转到的 URL。
  • 默认范围(Scope) 仅需要范围“profile”和“openid”,您可以根据需要添加其他范围。
  • 签名算法 使用默认值“RS256”。
  • 登录用户的 ID 字段 将此值设置为执行身份验证时与联邦 ID 匹配的字段名称。在大多数情况下,正确的名称是“oid”,它代表对象 ID。仅在极少数情况下才应将其设置为“oid”以外的值。
  • 即时 (JIT) 配置 如果您希望在用户首次登录时自动创建用户帐户,请勾选此项。新用户的详细信息基于声明中提供的属性。
  • 默认角色 分配给 JIT 配置期间创建的帐户的 角色(支持、标准或管理员)。如果您选择 无默认角色,则使用声明中指定的角色。

元数据文档

Entra ID 门户包含一个元数据文档(Metadata Document),其中列出了配置 SSO 时要使用的重要值。在门户中,你可以在 Endpoints -> OpenID Metadata Document 下找到此文档。

浏览本文档以查找上面列出的字段,以确保你的 Entra ID 配置包含适合你的设置的值。

回调URL

必须使用回调 URL 配置 Entra ID,以确保在用户通过身份验证后将登录令牌重定向回知行之桥。 知行之桥的适当回调 URL 具有以下结构:

[base_arc_url]/src/ssoCallback.rst

例如,如果知行之桥托管在端口 8001 上的 mydomain.com 上,则应使用以下重定向 URI: https://mydomain.com:8001/src/ssoCallback.rst

注意:该值区分大小写。