面向 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 范围的更多信息，请参阅 范围。

用户预置要求¶

要确保使用前面描述的映射配置成功进行身份验证，请确保满足以下要求：

• Entra ID 用户和 Snowflake 用户之间存在严格的一一对应关系。为每个将使用该集成的 Entra ID 用户指定或创建一个 Snowflake 用户。

• 每个 Entra ID 用户仅映射到一个 Snowflake 用户。对于电子邮件映射，Entra ID 主电子邮件必须与 Snowflake 用户的 EMAIL_ADDRESS 完全匹配。对于 UPN 映射，Entra ID UPN 必须与 Snowflake 用户的 LOGIN_NAME 完全匹配。

为减少手动管理工作量，您可选择配置从 Entra ID 到 Snowflake 的自动用户预置和取消预置。请参阅 配置自动预置 (https://learn.microsoft.com/en-us/entra/identity/saas-apps/snowflake-provisioning-tutorial)。

Create and configure the Cortex Agents¶

创建安全集成后，请确保至少有一个 Cortex Agent 对象 存在于您的 Snowflake 账户中，供 Teams 或 Microsoft 365 Copilot 集成使用。

若您已有可正常使用的代理，则此步骤无需采取进一步操作。

要创建新代理，请按照 说明。

从 Teams 商店安装应用程序¶

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

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

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

To recap, every user's default role in Snowflake must have the required privileges to access the agent's objects, as described in the access control requirements section of the Cortex Agents topic.

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

Snowflake recommends you create a dedicated, non-administrative role with the required permissions and set it as the default for the setup user. Alternatively, use the SECONDARY ROLES mechanism to grant the additional permissions without altering the user's primary default role, as follows:

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

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

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

2. Provide your Snowflake account URL where indicated, and select Connect Snowflake account.

   To find your account URL, log in to Snowsight and click the account selector in the bottom left corner of the page. The hostname portion of the URL is displayed at the top of the menu and is in the format your-organization-your-account. The full URL is your-organization-your-account.snowflakecomputing.cn.

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

After the setup passes final validation, the Teams app is connected to your Snowflake account and the agents are ready to use.

默认角色设置¶

The first step in troubleshooting access issues is to check the user's default role setting. To verify this setting, use the DESCRIBE USER command. Check the DEFAULT_ROLE property in the output. If the user's default role is incorrect, change it using the ALTER USER command.

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

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

要为 Cortex Agents 集成添加次要角色，请使用如下 SQL 命令。

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

所需权限¶

请确保集成运行的角色（每个用户的默认角色或允许的次要角色）具备 访问控制要求部分 所述的授权。

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

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

• EXTERNAL_OAUTH_ISSUER: This must be set to the correct Entra ID issuer URL, which is in the format https://login.microsoftonline.com/tenant-id/v2.0, where tenant-id is your organization's Microsoft tenant ID.

• EXTERNAL_OAUTH_JWS_KEYS_URL: This must be set to the correct JWS keys URL, which is in the format https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys, where tenant-id is your organization's Microsoft tenant ID.

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

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

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

This error message points to a mismatch between the user identifier sent by Entra ID and the corresponding user's record in Snowflake, usually because the Entra ID user identity does not map to exactly one Snowflake user. This can happen when the Snowflake user does not exist, when the mapped UPN or email address is incorrect, or when the mapping resolves to multiple Snowflake users (for example, if the mapping is performed using email address and multiple users share the same address).

The error message includes the UPN and email of the user attempting to log in. Use this information to verify the affected user's configuration using the DESCRIBE USER command. Make sure the user's NAME or EMAIL property matches the value of the same property in Entra ID for the corresponding user. When using email address mapping, each user in the Snowflake account that will use the integration must have a unique email address.

角色未在访问令牌中列出或已被过滤掉（错误代码 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：如果已启用该参数，请验证它是否不包含用户的默认角色。