连接 Microsoft Entra ID

本页介绍了如何将 Microsoft Entra ID 连接到 Gemini Enterprise。

首次设置数据源并导入数据后，数据存储区会按照您在设置期间选择的频率同步来自该来源的数据。

支持的版本

通过 Microsoft Graph API v1.0，Entra ID 连接器可支持所有托管版本的 Entra ID。

准备工作

在设置数据存储区和导入数据之前，您必须首先获取用于身份验证的客户端 ID 和密钥，并配置应用所需的最低权限。本部分将介绍如何完成这些任务。

为 Entra ID 设置访问权限控制

如需在 Gemini Enterprise 中强制执行数据源访问权限控制并保护数据安全，请确保您已配置身份提供方。

获取客户端 ID 和客户端密钥

  1. 创建 Entra ID 应用：

    1. 以管理员身份登录 Microsoft Entra 管理员中心，然后点击应用。
    2. 在应用下拉列表中，点击应用注册。
    3. 在应用注册页面中，点击新注册。
    4. 点击添加新注册，然后执行以下操作：
      • 输入应用的名称。
      • 在支持的账号类型下，选择仅此组织目录中的账号。
      • 在重定向 URI 下，添加一个指向 https://login.microsoftonline.com/common/oauth2/nativeclient 的Web重定向 URI。
    5. 点击注册。

  2. 保存凭证：

    在所注册应用的窗口中，保存以下值以供日后使用：

    1. 使用应用（客户端）ID 设置客户端 ID 参数。
    2. 使用目录（租户）ID 设置 Azure 租户参数。

  3. 创建客户端密钥：

    1. 前往证书和密钥。
    2. 点击新建客户端密钥，然后指定时长。
    3. 保存客户端密钥，并复制客户端密钥值以供日后使用。
save-client-secret-value
保存客户端密钥值

配置应用所需的最低权限

  1. 在所注册应用的窗口中，点击 API 权限。

  2. 在配置的权限下，选择 Microsoft Graph 并配置以下权限：

    • User.Read
    • User.Read.All (Application)

    如果您要注入 profileCardAttributes，请配置以下权限：

    • People.Read.All (Application)
    • PeopleSettings.Read.All (Application)
    • PeopleSettings.Read.All (Delegated)

  3. 为所有添加的权限授予管理员同意书。如要在身份验证流程中使用客户端凭证，需要获得管理员的同意。

最低权限

下表列出了创建 Entra ID 连接器所需的最低权限：

权限 使用原因 说明
User.Read 数据注入 在建立连接期间读取组织详细信息。
User.Read.All (Application) 数据注入 读取组织中的所有用户。
People.Read.All (Application) 数据注入 读取组织中所有用户的相关人员信息，例如联系人。
PeopleSettings.Read.All (Application) 数据注入 读取组织中所有用户的用户配置，例如 profileCardSettings。
PeopleSettings.Read.All (Delegated) 数据注入 读取组织中所有用户的用户配置，例如 profileCardSettings。

创建 Entra ID 数据存储区

如需使用 Google Cloud 控制台将数据从 Entra ID 同步到 Gemini Enterprise，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

    Gemini Enterprise

  2. 在导航菜单中，点击数据存储区。

  3. 点击 创建数据存储区。

  4. 在选择数据源页面上，滚动或搜索 Entra ID 以关联第三方来源。

  5. 在身份验证设置下，输入客户端 ID 和客户端密钥。

  6. 在高级选项下：

    • 如有需要，请点击启用静态 IP 地址。创建连接器后，您需要将注册的静态 IP 列入许可名单，以便同步运行成功。
    • 如要允许连接器提取用于向目录对象添加自定义属性的扩展属性，请选中启用扩展属性复选框。

    • 如果您想过滤已注入的用户信息，请提供自定义 SQL 过滤条件。过滤条件必须是有效的 SQL 字符串。

      过滤条件字符串中的键必须对应于以下字段：

      • Id
      • employeeType
      • onPremisesSyncEnabled
      • accountEnabled

      下面是有效 SQL 过滤条件的一些示例：

      id = 'abc' AND accountEnabled = true

employeeType='E' AND onPremisesSyncEnabled= true

    • 在 Azure 租户字段中，输入您在创建 Entra ID 应用时获得的 Azure 租户 ID。

    • 如要对连接器发送到 Entra ID 实例的查询应用速率限制，请在每秒查询次数上限字段中，指定每秒查询次数上限。默认值为 80 QPS。

    • 点击继续。

  7. 在选择要同步的实体下：

    • 点击用户个人资料。 如需根据 Id 过滤数据以进行数据注入，请点击过滤条件，然后执行以下操作：
      • 如需指定要包含在搜索索引中的数据，请选择包含在索引中，然后在 ID 字段中指定过滤条件字符串。
      • 如需指定要从搜索索引中排除的数据，请选择从索引中排除，然后在 ID 字段中指定过滤条件字符串。
    • 选择完全同步频率。

  8. 点击继续。

  9. 在配置数据连接器中，为数据存储区选择一个区域。

  10. 为数据连接器输入名称。

  11. 点击创建。Gemini Enterprise 会为您创建数据存储区，并在数据存储区页面上显示您的数据存储区。

  12. 如果您在高级选项下选择了启用静态 IP 地址，请查看为连接器注册的静态 IP 地址，并将其添加到 Entra ID 的许可名单中。

    1. 前往数据存储区页面，然后点击连接器名称，在其数据页面查看相关详情。
    2. 在静态 IP 字段中，点击查看并确认 IP 地址。
    3. 复制连接器的静态 IP 地址。
    4. 在 Microsoft Entra 管理员中心内，将静态 IP 地址添加到现有条件式访问权限政策中的指定位置或可信位置。如需了解详情，请参阅条件式访问权限：网络分配。

检查连接器状态

  1. 如需查看数据注入状态，请前往数据存储区页面，然后点击连接器名称，在其数据页面查看相关详情。当连接器开始同步数据时，连接器状态会从正在创建变为正在运行。注入完成后，状态会变为活跃，表明已设置与数据源的连接，并在等待下一次的计划同步。

    注入过程可能需要几分钟或几小时才能完成，具体取决于数据的大小。

  2. 在连接器状态变为活跃时，请前往实体标签页。

  3. 点击 userprofiles 实体。

  4. 检查注入的文档数量，并验证其是否与 Entra ID 中的用户数量一致。

以下标准用户属性会作为每个用户记录的一部分被注入：

Vertex AI 架构字段名称 Entra ID 属性名称
name.displayName 显示名称
name.familyName 姓氏
name.givenName 名字
name.username 用户主账号名称
email.value 邮箱
employeeId 员工 ID
personId
employeeType 员工类型
hireDate 员工聘用日期
department 部门
organizations.jobTitle 职位
organizations.location 办公地点
Phone 工作电话
managers.email、managers.personId 非直接属性（从直属经理到顶级经理的管理链）
directManager.personId 非直接属性（经理的 personId）
displayphoto.imagebinary.data Base64 编码的个人资料照片

如果 Entra ID 应用具有必要的权限来注入自定义属性，则会针对每条记录注入最多 15 个个人资料卡片属性。默认情况下，自定义属性不可搜索。

配置可搜索属性

如需使自定义属性可供搜索，请执行以下操作：

  1. 在 userprofiles 页面中，前往架构标签页。
  2. 点击修改。

  3. 取消选择可检索、可搜索和可编入索引的属性（例如地址），然后点击保存。

    修改按钮会保持非活动状态几分钟，然后才会重新激活。

  4. 当修改按钮处于有效状态时，点击修改。

  5. 为所需的自定义属性选择可检索、可搜索和可编入索引框。

  6. 启用搜索功能。

  7. 点击保存。

测试搜索引擎

配置搜索引擎后，请测试其功能，以验证它是否会根据用户访问权限返回准确的结果。

  1. 启用 Web 应用：

    1. 前往应用集成配置，然后切换到启用 Web 应用。

  2. 测试 Web 应用：

    1. 点击 Web 应用链接旁边的打开，然后以用户身份登录。

    2. 验证搜索结果是否仅限于用户可访问的内容。

预览人员搜索结果

  1. 在搜索应用中，前往预览，并在使用 Google IdP 时开始在控制台中搜索。

    • 或者，您也可以前往提供的链接，然后使用 IdP 账号登录以开始搜索。
    • 搜索结果会以人员卡片的形式显示，其中包含用户的详细信息，例如姓名、职位、电子邮件地址和个人资料照片。

  2. 点击人物卡片即可查看详细的个人资料页面，其中包含以下信息：

    • 名称
    • 个人资料照片
    • 职位
    • 部门
    • 管理链
    • 直接下属

  3. 如果注入自定义属性（个人资料卡片属性）并将其设为可编入索引、可搜索和可检索：

    • 按自定义属性值搜索时，系统只会返回包含这些属性的个人资料。
    • 自定义属性会显示在搜索结果中，但只能通过 API 访问，而无法通过 Vertex Search 界面访问。

为没有 SSO 的非 Google IdP 配置员工池

  1. 如果您的员工使用非 Google IdP、无法通过 Google 进行 SSO，或者不是 Google Workspace 客户，请按照 [为自定义数据源配置访问控制][data-source-access-control] 中所述设置工作区池，以启用员工搜索功能。

    借助员工池，您可以在 Google Cloud 控制台中管理并对来自外部身份提供方（如 Azure 或 Okta）的用户进行身份验证。

  2. 如需配置员工池并启用 Web 应用以实现顺畅的用户访问，请执行以下操作：

    1. 按照相应的设置手册在 Google Cloud 中创建组织级员工池：

      1. Azure OIDC 设置
      2. Azure SAML 设置
      3. Okta 和 OIDC 设置
      4. Okta 和 SAML 设置

    2. 在 Gemini Enterprise > 设置部分，为您在其中创建应用的区域配置员工池。

建议的速率限制

下表列出了根据用户数量建议的速率限制。 超出限制的请求会受到节流限制。

配额组 每秒请求次数
S（少于 50 位用户） 105
M（50-500 名用户） 150
L（超过 500 位用户） 240

已知限制

以下是 Entra ID 连接器的已知限制：

  • 不支持增量同步。
  • 不支持访问控制列表 (ACL)。 组织中的所有用户都可以访问这些用户。
  • 如果您在创建连接后将项目添加到 VPC Service Controls 边界，连接器同步运行会失败，并显示以下错误：Connector is blocked due to the project being added to the VPC-SC perimeter. Please re-create the data store. 请重新创建数据存储区，以便其在 VPC Service Controls 边界内运行。

错误消息

下表列出了您在使用 Entra ID 连接器时可能会收到的错误消息：

错误消息 说明 问题排查
Authorization_RequestDenied 权限不足，无法完成相应操作。 用户账号不包含读取数据所需的范围。 向用于创建连接的用户账号提供必需的范围。
未能检索到 OAuth 令牌信息 配置连接器时提供的客户端凭据无效。 验证以下各项：
  • 提供与客户端 ID 对应的客户端密钥。配置连接时，请指定客户端密钥值，而不是其密钥 ID。
  • 租户 ID 有效。
  • 客户端密钥未过期。如果客户端密钥已过期，请修改连接并指定新的客户端密钥。
由于项目已添加到 VPC-SC 边界，连接器被阻止。请重新创建数据存储区。 连接器是在项目添加到 VPC Service Controls 边界之前创建的。 重新创建数据存储区，使其能够在 VPC Service Controls 边界内运行。

后续步骤

  • 如需将数据存储区挂接到应用，请按照创建应用中的步骤创建应用并选择数据存储区。

  • 如需在设置应用和数据存储区后预览搜索结果的显示方式，请参阅获取搜索结果。