Cortex Agents for Microsoft Teams and Microsoft 365 Copilot¶

Granting consent for OAuth Resource principal¶

To grant consent for the Cortex Agents Bot OAuth Resource application service principal:

1. In your browser, navigate to https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe, where tenant-id is your organization’s Microsoft tenant ID.

   If you are not already signed in, you will be prompted to do so.

   A Permission requested dialog appears, showing the permission that the application requires.

2. Select Accept to grant the requested permission.

Granting consent for OAuth Client principal¶

This process displays two dialogs. Each is similar to the one for the OAuth Resource principal, but the permissions requested are different.

To grant consent for the Cortex Agents Bot Snowflake OAuth Client application service principal:

1. In your browser, navigate to https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086, where tenant-id is your organization’s Microsoft tenant ID.

   A Permissions requested (1 of 2) dialog appears, showing one set of permissions that the application requires.

2. Select Accept to grant the requested permissions.

   The second permission dialog appears (Permissions requested (2 of 2)).

3. Select Accept to grant the requested permissions.

{
  "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>"
  }
}

Confirming permission grants¶

After granting consent for both applications, you can confirm that the permissions were granted successfully by checking the Enterprise applications section of the Microsoft Entra ID portal.

1. Log in to the Microsoft Entra admin center if necessary.

2. Navigate to Enterprise Applications by typing “enterprise applications” in the search box, then selecting Enterprise applications in the results.

3. In the All applications list, find the two applications for which you just granted consent: Snowflake Cortex Agents Bot OAuth Resource and Snowflake Cortex Agents Bot OAuth Client. An easy way to do this is to search for “Snowflake Cortex Agent.”

   If both applications appear in the list, permissions have been correctly granted. If one or both applications are missing, try granting consent again.

Enabling Entra ID as an external OAuth provider¶

A Snowflake security integration object represents an integration with an external OAuth provider, in this case Microsoft Entra ID. This integration allows Snowflake to authenticate users who are logged into Microsoft Teams or Copilot.

The following SQL statement is an annotated template for creating the integration. This command must be executed by a role with ACCOUNTADMIN privileges. Replace the tenant-id placeholders with your Microsoft Tenant 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'

See CREATE SECURITY INTEGRATION (External OAuth) for a complete reference of the parameters available for this command.

Together, the EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM and EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE parameters link an Entra ID identity to a Snowflake identity. For authentication to succeed, the value of the specified claim in the JWT must exactly match the value of the specified attribute on a user object in Snowflake. The two main configurations Snowflake recommends are:

• Mapping by User Principal Name (UPN): Set the EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM parameter to ‘upn’ and the EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE parameter to ‘LOGIN_NAME’.

• Mapping by email address: Set the EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM parameter to ‘email’ and the EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE parameter to ‘EMAIL_ADDRESS’.

The example statement above uses the email address mapping configuration, but also specifies UPN in the EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM parameter, allowing you to change the mapping method by changing only the EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE.

The example statement also enables EXTERNAL_OAUTH_ANY_ROLE_MODE, so that the user’s default role is used.

For more information on OAuth scopes, see Scopes.

Prepare the Cortex Agent definition¶

Once security integration is configured, you must prepare the agent’s environment and definition within Snowflake. This involves creating the necessary database objects and defining the agent’s logic in a single JSON object. The definition specifies the agent’s instructions, its tools (like Cortex Analyst and Cortex Search), and the resources for those tools. The schema definition follows the Cortex Agent API request body schema with some additions. The following is the top-level structure of the JSON object:

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

Upload the agent definition to a Snowflake stage and make sure it is accessible to all end users who will use the agent.

You can enhance the user experience by setting two optional fields for search results and conversational guidance:

• Search citations can be provided a human-readable title and a direct link to the source document by supplying two optional fields in the tool_resources definition of the search tool:

  • title_column is a column that contains the human-readable title of a document.

  • id_column is a column that contains a unique identifier for the document, which Cortex Search uses to construct a link to the document.

• Starter prompts can be provided to guide users in formulating their questions in the starter_prompts field at the top level of the agent definition.

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

  Copy

Grant required privileges to end users¶

For end users to successfully interact with a Cortex Agent in Teams, their default Snowflake role (or other designated role) must have privileges grants on all the underlying objects:

• All grants listed in the access control requirements section of the Cortex Agents topic

• READ access to the stage containing the agent’s JSON definition

• USAGE on the warehouse assigned to the agent

Install the app from the Teams store¶

All users must install the Cortex Agents app from the Microsoft Teams store. To install the app, search for “Snowflake Cortex Agents” in the Teams app store, then click Add to install the app.

Connect your Snowflake account to the Teams app¶

The first user to interact with the Cortex Agents app in Teams is prompted to connect their Snowflake account to the app. This user must have the ACCOUNTADMIN or SECURITYADMIN role in Snowflake for this step to succeed.

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, along with READ access to the stage containing the agent’s JSON definition and USAGE on the agent’s warehouse. (The user’s default role is specified by the DEFAULT_ROLE setting in the user’s profile.)

Security integrations block the main Snowflake administrative roles by default. Therefore, you cannot use administrative roles such as ACCOUNTADMIN as the default role for the user that will set up the Teams bot. For information on this restriction, see BLOCKED_ROLES_LIST in the CREATE SECURITY INTEGRATION topic.

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 = ('<integration_specific_role>');

To set up the Teams bot, follow these steps:

1. Click I’m the Snowflake administrator, below the notice stating that an administrator needs to configure Snowflake for the Teams enticement, to begin the process.

2. Provide your Snowflake account URL where indicated.

   To find this 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.com.

   The configuration wizard verifies that the URL leads to a valid Snowflake instance in the Azure US East 2 region and confirms that your user has access to it and has the required administrative privileges.

   Note

   You may see a warning instructing you to ensure that the security integration uses “Microsoft identity platform access token v2.0’. You can safely ignore this warning; the Snowflake security integration token format is compatible.

3. After this verification passes, a form appears requesting the following configuration details:

   • Account alias: A user-friendly name for this Snowflake account which appears in the Teams interface, for example “Sales Analytics.”

   • Agent definition path: The fully-qualified path to the agent’s JSON definition file in a Snowflake stage, in the format @stage_name/path_to_definition_file, such as @my_cortex_agents/my_agent.json.

   • Default warehouse: The name of the Snowflake warehouse that the agent uses to run queries.

   Enter this information, then click Finalize account configuration.

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

Default role setting¶

The first step in troubleshooting access issues is to check the user’s default role setting. To verify this setting, run the DESCRIBE USER command and 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>';

If changing the user’s primary DEFAULT_ROLE is not feasible, you can use the Snowflake’s secondary roles mechanism. A user can perform actions using the combined privileges of their primary and active secondary roles. This lets you to grant an additional, integration-specific role to the user without altering their primary role.

To add a secondary role for the Cortex Agents integration, use SQL commands like the following. To ensure that you do not remove any secondary roles already assigned to the user, take note of the DEFAULT_SECONDARY_ROLES property in the output of DESCRIBE USER. Include these pre-existing roles when adding the integration-specific role.

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>');

Required permissions¶

The user’s default role (or a default secondary role) must possess the privileges described below.

• Cortex AI function access via the SNOWFLAKE.CORTEX_USER role. By default, this role is granted to the PUBLIC role, so all users can access Cortex AI functions. If your organization has removed SNOWFLAKE.CORTEX_USER from PUBLIC, you must explicitly grant it to the role that the agent runs under.

• If the agent uses the Cortex Analyst tool, the role must also have the following privileges:

  • USAGE on all databases and schemas referenced in the semantic model

  • SELECT on all tables and views referenced in the semantic model

  • READ access on the stage containing the semantic model file(s)

• If the agent uses a Cortex Search service, the role must have USAGE on the specific service used.

Invalid OAuth access token (error code 390303)¶

This error can indicate that one or more property values in the security integration are incorrect, preventing Snowflake from validating the access token received from Entra ID. To rectify this, check the following fields in the security integration. In particular, make sure the tenant ID is correct in the 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: This must include the correct audience for the Cortex Agents Bot OAuth Resource application, which is the application ID 5a840489-78db-4a42-8772-47be9d833efe.

Update any incorrect values using the ALTER SECURITY INTEGRATION command.

Incorrect username or password (error code 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 does not map exactly one Snowflake user. This can happen when the Snowflake user does not exist (or 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. If using email address mapping, ensure that the email address is unique across all users in the Snowflake account.

Role not listed in the access token or was filtered out (error code 390317)¶

This error occurs when Snowflake cannot assign a role to the user based on the information in the OAuth access token. The access token is configured with the session:role-any scope, which allows the user to assume any of their assigned roles in Snowflake. However, the security integration must be explicitly configured to permit this behavior.

Use the DESCRIBE SECURITY INTEGRATION command to check the value of the EXTERNAL_OAUTH_ANY_ROLE_MODE property, then change it to ENABLE or 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';

Role specified in the connect string is not granted to this user (error code 390186)¶

This error occurs when Snowflake security integration doesn’t allow the user’s default role to use the security integration.

To resolve this, check the following properties in the output of DESCRIBE SECURITY INTEGRATION:

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST: If the parameter is enabled, verify that it contains the user’s default role.

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST: If the parameter is enabled, verify that it does not contain the user’s default role.