面向 Microsoft Teams 和 Microsoft 365 Copilot 的 Cortex Agents¶

向 OAuth Resource 主体授予同意¶

要授予 Cortex Agents Bot OAuth Resource 应用程序服务主体的同意，请执行以下操作：

1. 在浏览器中，导航到 https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe，其中 tenant-id 是贵组织的 Microsoft 租户 ID。

   如果您尚未登录，系统将提示您进行登录。

   此时将显示一个 Permission requested 对话框，显示应用程序所需的权限。

2. 选择 Accept 以授予所请求的权限。

向 OAuth Client 主体授予同意¶

此流程会显示两个对话框。每个都类似于 OAuth Resource 主体的权限请求界面，但请求的权限不同。

要授予 Cortex Agents Bot Snowflake OAuth Client 应用程序服务主体的同意，请执行以下操作：

1. 在浏览器中，导航到 https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086，其中 tenant-id 是贵组织的 Microsoft 租户 ID。

   此时将显示一个 Permissions requested (1 of 2) 对话框，显示应用程序所需的一组权限。

2. 选择 Accept 以授予所请求的权限。

   此时将显示第二个权限对话框 (Permissions requested (2 of 2))。

3. 选择 Accept 以授予所请求的权限。

{
  "error": {
    "code": "ServiceError",
    "message": "Missing required query string parameter: code. Url = https://unitedstates.token.botframework.com/.auth/web/redirect?admin_consent=True&tenant=<TENANT-ID>"
  }
}

确认权限授予¶

在对两个应用程序授予同意后，您可以通过查看 Microsoft Entra ID 门户的 Enterprise applications 部分来确认权限是否已成功授予。

1. 如有必要，请登录到 Microsoft Entra 管理中心 (https://entra.microsoft.com/)。

2. 在搜索框中输入“enterprise applications”导航到 Enterprise Applications，然后在结果中选择 Enterprise applications。

3. 在 All applications 列表中，找到刚刚授予同意的两个应用程序：Snowflake Cortex Agents Bot OAuth Resource 和 Snowflake Cortex Agents Bot OAuth Client。一种简单的方法是搜索“Snowflake Cortex Agent”

   如果两个应用程序都出现在列表中，说明权限已正确授予。如果缺少一个或两个应用程序，请重新尝试授予同意。

启用 Entra ID 作为外部提供商 OAuth¶

Snowflake 安全集成对象表示与外部 OAuth 提供商（在本例中为 Microsoft Entra ID）的集成。此集成允许 Snowflake 对登录 Microsoft Teams 或 Copilot 的用户进行身份验证。

以下 SQL 语句是一个带注释的模板，用于创建此集成。此命令必须由具有 ACCOUNTADMIN 权限的角色执行。请将其中的 tenant-id 占位符替换为您的 Microsoft 租户 ID。

CREATE OR REPLACE SECURITY INTEGRATION entra_id_cortex_agents_integration
    TYPE = EXTERNAL_OAUTH
    ENABLED = TRUE
    EXTERNAL_OAUTH_TYPE = AZURE
    EXTERNAL_OAUTH_ISSUER = 'https://login.microsoftonline.com/<tenant-id>/v2.0'
    EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys'
    EXTERNAL_OAUTH_AUDIENCE_LIST = ('5a840489-78db-4a42-8772-47be9d833efe')
    EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = ('email', 'upn')
    EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'email_address'
    EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE'

有关此命令可用参数的完整参考，请参阅 CREATE SECURITY INTEGRATION (External OAuth)。

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 和 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 参数共同将 Entra ID 身份与 Snowflake 身份关联起来。要使身份验证成功，JWT 中指定声明的值必须与 Snowflake 用户对象上指定属性的值完全匹配。Snowflake 推荐的两种主要配置是：

• 按用户主体名称映射 (UPN)：将 EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 参数设置为 “upn”，并将 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 参数设置为“LOGIN_NAME”。

• 按电子邮件地址映射：将 EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 参数设置为“email”，并将 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 参数设置为“EMAIL_ADDRESS”。

上面的示例语句使用了电子邮件地址映射配置，但同时在 EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM 参数中指定了 UPN，允许您通过仅更改 EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE 来更改映射方法。

该示例语句还启用了 EXTERNAL_OAUTH_ANY_ROLE_MODE，因此会使用用户的默认角色。

有关 OAuth 范围的更多信息，请参阅 范围。

准备 Cortex Agent 定义¶

配置安全集成后，您必须在 Snowflake 中准备代理的环境和定义。这包括创建必要的数据库对象并在单个 JSON 对象中定义代理的逻辑。该定义会指定代理的指令、其工具（如 Cortex Analyst 和 Cortex Search）以及这些工具的资源。架构定义遵循 Cortex Agent API 请求正文架构，并在此基础上有所扩展。以下是 JSON 对象的顶层结构：

{
    "model": ...,
    "response_instruction": ...,
    "experimental": ...
    "tools": ...
    "tool_resources": ...
    "tool_choice": ...
    "starter_prompts": ...
}

将代理定义上传到 Snowflake 暂存区，并确保将使用该代理的所有最终用户都可以访问该定义。

您可以通过为搜索结果和对话指导设置两个可选字段来增强用户体验：

• 通过在搜索工具的 tool_resources 定义中提供两个可选字段，可以为搜索引用来源提供人类可读的标题和指向源文档的直接链接：

  • title_column 是包含人类可读的文档标题的列。

  • id_column 是包含文档唯一标识符的列，Cortex Search 会使用该标识符来构建指向文档的链接。

• 您可以在代理定义的顶层 starter_prompts 字段中提供入门提示，来指导用户提出问题。

  {
      ....
      "starter_prompts": ["prompt #1", "prompt #2", ...],
      ...
  }
  

  Copy

向最终用户授予所需权限¶

为了使最终用户成功在 Teams 中与 Cortex Agent 进行交互，他们的默认 Snowflake 角色（或其他指定角色）必须拥有所有底层对象的权限授予：

• Cortex Agents 主题的 访问控制要求 部分中列出的所有授权

• 包含代理 JSON 定义的暂存区 READ 访问权限

• 在分配给代理的仓库的 USAGE

从 Teams 商店安装应用程序¶

所有用户都必须从 Microsoft Teams 商店安装 Cortex Agents 应用程序。要安装该应用程序，请在 Teams 应用商店中搜索 “Snowflake Cortex Agents”，然后点击 Add 即可安装该应用程序。

将 Snowflake 账户连接到 Teams 应用程序¶

系统会提示在 Teams 中与 Cortex Agents 应用程序进行交互的第一个用户将其 Snowflake 账户连接到该应用程序。此用户必须在 Snowflake 中拥有 ACCOUNTADMIN 或 SECURITYADMIN 角色才能成功完成此步骤。

总而言之，每个用户在 Snowflake 中的默认角色都必须具有访问代理对象所需的权限，如 Cortex Agents 主题的 访问控制要求部分 所述，还必须具有访问包含代理 JSON 定义的暂存区和 USAGE 代理仓库的 READ 访问权限。（用户的默认角色由用户配置文件中的 DEFAULT_ROLE 设置指定。）

默认情况下，安全集成会阻止 Snowflake 的主要管理角色。因此，像 ACCOUNTADMIN 这样的管理角色，不能作为设置 Teams Bot 用户的默认角色。有关此限制的信息，请参阅 CREATE SECURITY INTEGRATION 主题中的 BLOCKED_ROLES_LIST。

Snowflake 建议您创建一个具有所需权限的专用非管理角色，并将其设置为设置用户的默认角色。或者，使用 SECONDARY ROLES 机制在不更改用户的主要默认角色的情况下授予额外权限，如下所示：

GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('<integration_specific_role>');

要设置 Teams Bot，请按照以下步骤操作：

1. 在提示“管理员需要为 Teams 激励功能配置 Snowflake”的通知下方，点击 I'm the Snowflake administrator 开始配置流程。

2. 按提示提供 Snowflake 账户 URL。

   要查找此 URL，请登录 Snowsight，点击页面左下角的账户选择器。菜单顶部会显示 URL 的主机名部分，格式为 your-organization-your-account。完整 URL 格式为 your-organization-your-account.snowflakecomputing.cn。

   配置向导会验证 URL 是否指向 Azure US 东部 2 区域的有效 Snowflake 实例，并确认您的用户是否有访问权限，以及是否具有所需的管理权限。

   备注

   您可能会看到一条警告，提示需要确保安全集成使用 “Microsoft 身份平台访问令牌 v2.0”。您可以放心地忽略此警告；因为 Snowflake 的安全集成令牌格式是兼容的。

3. 验证通过后，此时将显示一个表单，要求提供以下配置详细信息：

   • 账户别名： 此 Snowflake 账户的易读名称，显示在 Teams 界面中，例如“销售分析”。

   • 代理定义路径： Snowflake 暂存区代理 JSON 定义文件的完全限定路径，格式为 @stage_name/path_to_definition_file，例如 @my_cortex_agents/my_agent.json。

   • 默认仓库： 代理用来运行查询的 Snowflake 仓库的名称。

   输入此信息，然后点击 Finalize account configuration。

设置通过最终验证后，Teams 应用程序将连接到您的 Snowflake 账户，代理即可使用。

默认角色设置¶

故障排除访问问题的第一步是检查用户的默认角色设置。要验证此设置，请运行 DESCRIBE USER 命令并检查输出中的 DEFAULT_ROLE 属性。如果用户的默认角色不正确，请使用 ALTER USER 命令进行更改。

ALTER USER <user_name> SET DEFAULT_ROLE = '<correct_role>';

如果更改用户的主要 DEFAULT_ROLE 角色不可行，则可以使用 Snowflake 的次要角色机制。用户可以使用其主要角色和活动次要角色的组合权限执行操作。这允许为用户额外授予集成专用的角色，而不必更改主要角色。

要为 Cortex Agents 集成添加次要角色，请使用如下 SQL 命令。为确保您不会移除已分配给用户的任何次要角色，请在 DESCRIBE USER 的输出中记下 DEFAULT_SECONDARY_ROLES 属性。在添加特定于集成的角色时包括这些先前存在的角色。

DESCRIBE USER <user_name>;  -- take note of DEFAULT_SECONDARY_ROLES
GRANT ROLE <integration_specific_role> TO USER <user_name>;
ALTER USER <user_name> SET DEFAULT_SECONDARY_ROLES = ('<pre_existing_role_1>', ....,
    '<integration_specific_role>');

所需权限¶

用户的默认角色（或默认的次要角色）必须拥有下述权限。

• 通过 SNOWFLAKE.CORTEX_USER 角色访问 Cortex AI 函数。默认情况下，此角色会被授予 PUBLIC 角色，因此所有用户都可以访问 Cortex AI 函数。如果您的组织已从 PUBLIC 移除 SNOWFLAKE.CORTEX_USER，则必须将其明确授予代理运行的角色。

• 如果代理使用 Cortex Analyst 工具，则该角色还必须具有以下权限：

  • 对语义模型涉及的所有数据库和架构具备 USAGE 权限

  • 对语义模型引用的所有表和视图具备 SELECT 权限

  • 对包含语义模型的暂存区具备 READ 访问权限

• 如果代理使用 Cortex Search 服务，则该角色必须对所使用的特定服务具备 USAGE 权限。

OAuth 访问令牌无效（错误代码 390303）¶

此错误可能表示安全集成中的一个或多个属性值不正确，从而导致 Snowflake 无法验证从 Entra ID 收到的访问令牌。要纠正此问题，请检查安全集成中的以下字段。特别是，请确保租户 ID 在 URLs 中是正确的。

• EXTERNAL_OAUTH_ISSUER： 必须将其设置为正确的 Entra ID 签发方 URL，格式为 https://login.microsoftonline.com/<tenant-id>/v2.0，其中 tenant-id 是贵组织的 Microsoft 租户 ID。

• EXTERNAL_OAUTH_JWS_KEYS_URL： 必须将其设置为正确的 JWS 密钥 URL，格式为 https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys，其中 tenant-id 是贵组织的 Microsoft 租户 ID。

• EXTERNAL_OAUTH_AUDIENCE_LIST： 这必须包括 Cortex Agents Bot OAuth Resource 应用程序（即应用程序 ID 5a840489-78db-4a42-8772-47be9d833efe）的正确受众。

使用 ALTER SECURITY INTEGRATION 命令更新任何不正确的值。

用户名或密码不正确（错误代码 390304）¶

此错误消息表明 Entra ID 发送的用户标识符与 Snowflake 中相应的用户记录不匹配，这通常是因为 Entra ID 没有精确映射到某个 Snowflake 用户。当 Snowflake 用户不存在（或者映射 UPN 或电子邮件地址不正确），或者映射解析为多个 Snowflake 用户时（例如，如果使用电子邮件地址执行映射且多个用户共享同一个地址），就会发生这种情况。

错误消息包括尝试登录的用户的 UPN 和电子邮件地址。使用此信息可使用 DESCRIBE USER 命令验证受影响用户的配置。确保用户 NAME 或 EMAIL 属性与 Entra ID 中相应用户的相同属性的值相匹配。如果使用电子邮件地址映射，请确保 Snowflake 账户中所有用户的电子邮件地址是唯一的。

角色未在访问令牌中列出或已被过滤掉（错误代码 390317）¶

当 Snowflake 无法根据 OAuth 访问令牌中的信息向用户分配角色时，就会发生此错误。访问令牌使用 session:role-any 范围进行配置，允许用户代入 Snowflake 中的任何分配角色。但是，必须明确配置安全集成才能允许这种行为。

使用 DESCRIBE SECURITY INTEGRATION 命令检查 EXTERNAL_OAUTH_ANY_ROLE_MODE 属性的值，然后将其更改为 ENABLE 或 ENABLE_FOR_LOGIN。

DESCRIBE SECURITY INTEGRATION entra_id_cortex_agents_integration;

ALTER SECURITY INTEGRATION entra_id_cortex_agents_integration
    SET EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';

未向此用户授予连接字符串中指定的角色（错误代码 390186）¶

当 Snowflake 安全集成不允许用户的默认角色使用安全集成时，就会出现此错误。

要解决此问题，请检查 DESCRIBE SECURITY INTEGRATION 输出中的以下属性：

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST：如果已启用该参数，请验证它是否包含用户的默认角色。

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST：如果已启用该参数，请验证它是否不包含用户的默认角色。