Cortex Agents pour Microsoft Teams et Microsoft 365 Copilot¶

Donner son accord pour le principal de ressource OAuth¶

Pour donner votre accord au principal de service de l’application de ressource OAuth du Bot Cortex Agents :

1. Dans votre navigateur, accédez à https://login.microsoftonline.com/<id-client>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe, où tenant-id est le client Microsoft de votre organisation ID.

   Si vous n’êtes pas encore connecté, vous serez invité à le faire.

   Une boîte de dialogue Permission requested apparaît, indiquant l’autorisation dont l’application a besoin.

2. Sélectionner Accept pour accorder l’autorisation demandée.

Donner son accord pour le principal du client OAuth¶

Ce processus affiche deux boîtes de dialogue. Chacun est similaire à celui de le principal de ressource OAuth, mais les autorisations demandées sont différentes.

Pour donner votre accord au principal de service de l’application client OAuth Snowflake du Bot Cortex Agents :

1. Dans votre navigateur, accédez à https://login.microsoftonline.com/<id-client>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086, où tenant-id est le client Microsoft de votre organisation ID.

   Une boîte de dialogue Permissions requested (1 of 2) apparaît, montrant un ensemble d’autorisations dont l’application a besoin.

2. Sélectionner Accept pour accorder les autorisations demandées.

   La deuxième boîte de dialogue d’autorisation apparaît (Permissions requested (2 of 2)).

3. Sélectionner Accept pour accorder les autorisations demandées.

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

Confirmation des accords d’autorisations¶

Après avoir accordé le consentement pour les deux applications, vous pouvez confirmer que les autorisations ont été accordées correctement en vérifiant la section Enterprise applications du portail ID Microsoft Entra.

1. Connectez-vous au Centre d’administration Microsoft Entra si nécessaire.

2. Naviguez jusqu’aux applications d’entreprise en saisissant « applications d’entreprise » dans le champ de recherche, puis en sélectionnant Enterprise applications dans les résultats.

3. Dans la liste All applications, cherchez les deux applications pour lesquelles vous venez de donner votre accord : Ressource OAuth du Bot Snowflake Cortex Agents et Client OAuth du Bot Snowflake Cortex Agents. Un moyen simple de le faire est de rechercher « Snowflake Cortex Agent ».

   Si les deux applications apparaissent dans la liste, les autorisations ont été correctement accordées. S’il manque l’une ou les deux applications, essayez à nouveau de donner votre accord.

L’activation de l’ID Entra en tant que fournisseur OAuth externe¶

Un objet d’intégration de sécurité Snowflake représente une intégration avec un fournisseur OAuth externe, en l’occurrence l’ID Microsoft Entra. Cette intégration permet à Snowflake d’authentifier les utilisateurs qui sont connectés à Microsoft Teams ou Copilot.

L’instruction SQL qui suit est un modèle annoté pour la création de l’intégration. Cette commande doit être exécutée par un rôle doté de privilèges ACCOUNTADMIN. Remplacer les espaces tenant-id réservés avec votre ID client Microsoft.

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'

Voir CREATE SECURITY INTEGRATION (External OAuth) pour une référence complète des paramètres disponibles pour cette commande.

Ensemble, les paramètres EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM et EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE lient une identité ID Entra avec une identité Snowflake. Pour que l’authentification réussisse, la valeur de la demande spécifiée dans le JWT doit correspondre exactement à la valeur de l’attribut spécifié sur un objet utilisateur dans Snowflake. Les deux principales configurations recommandées par Snowflake sont les suivantes :

• Mappage par nom d’utilisateur principal (UPN) : Définissez le paramètre EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM sur “upn” et le paramètre EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE sur “LOGIN_NAME”.

• Mappage par adresse e-mail : Définissez le paramètre EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM sur “email” et le paramètre EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE sur “EMAIL_ADDRESS”.

L’exemple d’instruction ci-dessus utilise la configuration de mappage des adresses e-mail, mais spécifie également l’UPN dans le paramètre EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM, ce qui vous permet de modifier la méthode de mappage en modifiant uniquement le EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE.

L’instruction d’exemple permet également d’effectuer des EXTERNAL_OAUTH_ANY_ROLE_MODE, de sorte que le rôle par défaut de l’utilisateur soit utilisé.

Pour plus d’informations sur les champs d’application OAuth, voir Champs d’application.

Préparer la définition de l’Agent Cortex¶

Une fois l’intégration de sécurité configurée, vous devez préparer l’environnement de l’agent et la définition dans Snowflake. Cela implique la création des objets de base de données nécessaires et la définition de la logique de l’agent dans un seul objet JSON. La définition spécifie les instructions de l’agent, ses outils (tels que Cortex Analyst et Cortex Search) et les ressources de ces outils. La définition du schéma suit le :ref:` schéma du corps de la requête APICortex Agent <label-cortex-agent-rest-api-request_body>` avec quelques ajouts. Voici la structure de premier niveau de l’objet JSON :

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

Téléchargez la définition de l’agent dans une zone de préparation Snowflake et assurez-vous qu’elle soit accessible à tous les utilisateurs finaux qui utiliseront l’agent.

Vous pouvez améliorer l’expérience utilisateur en définissant deux champs facultatifs pour les résultats de la recherche et le guide conversationnel :

• Les citations de recherche peuvent être accompagnées d’un titre lisible par l’utilisateur et d’un lien direct vers le document source en renseignant deux champs facultatifs dans la définition tool_resources de l’outil de recherche :

  • title_column est une colonne qui contient le titre lisible par l’utilisateur d’un document.

  • id_column est une colonne qui contient un identificateur unique pour le document, identificateur que Cortex Search utilise pour construire un lien vers le document.

• Des invites de démarrage peuvent être fournies pour aider les utilisateurs à formuler leurs questions dans le champ starter_prompts au niveau supérieur de la définition de l’agent.

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

  Copy

Accorder les privilèges requis aux utilisateurs finaux¶

Pour que les utilisateurs finaux interagissent correctement avec un Cortex Agent dans Teams, leur rôle Snowflake par défaut (ou un autre rôle désigné) doit disposer de privilèges accordés sur tous les objets sous-jacents :

• Tous les accords répertoriées dans la section des exigences de contrôle d’accès de la rubrique Cortex Agents

• Accès READ à la zone de préparation contenant la définition de l’agent JSON

• USAGE sur l’entrepôt affecté à l’agent

Installez l’application depuis Teams Store¶

Tous les utilisateurs doivent installer l’application Cortex Agents à partir de Microsoft Teams Store. Pour installer l’application, recherchez « Snowflake Cortex Agents » dans Teams Store, puis cliquez sur Add pour installer l’application.

Connecter votre compte Snowflake à l’application Teams¶

Le premier utilisateur qui interagit avec l’application Cortex Agents dans Teams est invité à connecter son compte Snowflake à l’application. Cet utilisateur doit disposer du rôle ACCOUNTADMIN ou SECURITYADMIN dans Snowflake pour passer cette étape.

Pour récapituler, le rôle par défaut de chaque utilisateur dans Snowflake doit disposer des privilèges requis pour accéder aux objets de l’agent, comme décrit dans la section Exigences de contrôle d’accès de la rubrique Cortex Agents, ainsi qu’un accès READ à la zone de préparation contenant la définition de l’agent JSON et USAGE sur l’entrepôt de l’agent. (Le rôle par défaut de l’utilisateur est spécifié par le paramètre DEFAULT_ROLE dans le profil de l’utilisateur).

Les intégrations de sécurité bloquent par défaut les rôles administratifs principaux de Snowflake. Par conséquent, vous ne pouvez pas utiliser des rôles administratifs tels que ACCOUNTADMIN comme rôle par défaut pour l’utilisateur qui configurera le bot Teams. Pour plus d’informations sur cette restriction, voir BLOCKED_ROLES_LIST dans la rubrique CREATE SECURITY INTEGRATION.

Snowflake vous recommande de créer un rôle dédié, non administratif, avec les autorisations requises et de le définir par défaut pour l’utilisateur en charge de la configuration. Vous pouvez également utiliser le mécanisme SECONDARY ROLES pour accorder les autorisations supplémentaires sans modifier le rôle principal par défaut de l’utilisateur, comme suit :

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

Pour configurer le bot Teams, suivez les étapes suivantes :

1. Cliquez sur I’m the Snowflake administrator, sous l’avertissement indiquant qu’un administrateur doit configurer Snowflake pour l’exécution Teams, pour démarrer le processus.

2. Indiquez l’URL de votre compte Snowflake à l’endroit indiqué.

   Pour trouver cette URL, connectez-vous à Snowsight et cliquez sur le sélecteur de compte dans le coin inférieur gauche de la page. La partie nom d’hôte de l’URL s’affiche en haut du menu et se présente sous le format your-organization-your-account. L’URL complète est your-organization-your-account.snowflakecomputing.com.

   L’assistant de configuration vérifie que l’URL conduit à une instance de Snowflake valide dans la Région Est 2 Azure US et confirme que votre utilisateur y a accès tout en disposant des privilèges administratifs requis.

   Note

   Vous pouvez voir un avertissement vous demandant de vous assurer que l’intégration de sécurité utilise le « jeton d’accès à la plateforme d’identité Microsoft v2.0 ». Vous pouvez ignorer cet avertissement sans problème. Le format du jeton d’intégration de sécurité Snowflake est compatible.

3. Une fois cette vérification passée, un formulaire apparaît et demande les détails de configuration suivants :

   • Alias de compte : un nom convivial pour ce compte Snowflake qui apparaît dans l’interface Teams, par exemple : « Analyse des ventes ».

   • Chemin de définition de l’agent : le chemin complet vers le fichier de définition JSON de l’agent dans une zone de préparation Snowflake, au format @stage_name/path_to_definition_file, comme @my_cortex_agents/my_agent.json.

   • Entrepôt par défaut : nom de l’entrepôt Snowflake que l’agent utilise pour exécuter les requêtes.

   Saisissez ces informations, puis cliquez sur Finalize account configuration.

Une fois la configuration validée, l’application Teams est connectée à votre compte Snowflake et l’agent est prêt à être utilisé.

Paramètre de rôle par défaut¶

La première étape de la résolution des problèmes d’accès consiste à vérifier le paramètre de rôle par défaut de l’utilisateur. Pour vérifier ce paramètre, exécutez la commande DESCRIBE USER et vérifiez la propriété DEFAULT_ROLE dans la sortie. Si le rôle par défaut de l’utilisateur est incorrect, modifiez-le à l’aide de la commande ALTER USER.

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

Si le rôle principal DEFAULT_ROLE de l’utilisateur n’est pas réalisable, vous pouvez utiliser le mécanisme de rôles secondaires de Snowflake. Un utilisateur peut effectuer des actions en utilisant les privilèges combinés de ses rôles primaire et secondaire actif. Cela vous permet d’attribuer un rôle supplémentaire spécifique à l’intégration à l’utilisateur sans modifier son rôle principal.

Pour ajouter un rôle secondaire à l’intégration Cortex Agents, utilisez les commandes SQL comme les suivantes. Pour vous assurer que vous ne supprimez pas les rôles secondaires déjà attribués à l’utilisateur, prenez note de la propriété DEFAULT_SECONDARY_ROLES dans la sortie de DESCRIBE USER. Incluez ces rôles préexistants lors de l’ajout du rôle spécifique à l’intégration.

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

Autorisations requises¶

Le rôle par défaut de l’utilisateur (ou un rôle secondaire par défaut) doit posséder les privilèges décrits ci-dessous.

• Accès à la fonction Cortex AI via le rôle SNOWFLAKE.CORTEX_USER. Par défaut, ce rôle est accordé au rôle PUBLIC, pour que tous les utilisateurs puissent accéder aux fonctions Cortex AI. Si votre organisation a supprimé SNOWFLAKE.CORTEX_USER de PUBLIC, vous devez l’accorder explicitement au rôle sous lequel l’agent s’exécute.

• Si l’agent utilise l’outil Cortex Analyst, le rôle doit également disposer des privilèges suivants :

  • USAGE sur l’ensemble des bases de données et schémas référencés dans le modèle sémantique

  • SELECT sur toutes les tables et vues référencées dans le modèle sémantique

  • Accès READ à la zone de préparation contenant le(s) fichier(s) de modèle sémantique

• Si l’agent utilise un service Cortex Search, le rôle doit avoir USAGE sur le service spécifique utilisé.

Jeton d’accès OAuth non valide (code d’erreur 390303)¶

Cette erreur peut indiquer qu’une ou plusieurs valeurs de propriété dans l’intégration de sécurité sont incorrectes, ce qui empêche Snowflake de valider le jeton d’accès reçu de Entra ID. Pour y remédier, vérifiez les champs suivants dans l’intégration de sécurité. En particulier, assurez-vous que le client ID est correct dans le URLs.

• EXTERNAL_OAUTH_ISSUER : doit être réglé sur la bonne URL émettrice d’ID Entra, qui est au format https://login.microsoftonline.com/<tenant-id>/v2.0, où tenant-id est le client Microsoft de votre organisation ID.

• EXTERNAL_OAUTH_JWS_KEYS_URL : doit être réglé sur la bonne URL de clés JWS, qui est au format https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys, où tenant-id est le client Microsoft de votre organisation ID.

• EXTERNAL_OAUTH_AUDIENCE_LIST : doit inclure l’audience correcte pour le bot de l’application de ressources OAuth Cortex Agents, qui est l’application ID 5a840489-78db-4a42-8772-47be9d833efe.

Mettre à jour les valeurs incorrectes à l’aide de la commande ALTER SECURITY INTEGRATION.

Nom d’utilisateur ou mot de passe incorrect (code d’erreur 390304)¶

Ce message d’erreur indique une erreur entre l’identificateur de l’utilisateur envoyé par ID Entra et l’enregistrement de l’utilisateur correspondant dans Snowflake, généralement parce que l’ID Entra ne mappe pas exactement un utilisateur de Snowflake. Cela peut se produire lorsque l’utilisateur Snowflake n’existe pas (ou l’UPN mappé ou l’adresse e-mail est incorrecte), ou lorsque le mappage se résout en plusieurs utilisateurs Snowflake (par exemple, si le mappage est effectué en utilisant une adresse e-mail et que plusieurs utilisateurs partagent la même adresse).

Le message d’erreur comprend l’UPN et l’e-mail de l’utilisateur qui tente de se connecter. Utilisez ces informations pour vérifier la configuration de l’utilisateur concerné à l’aide de la commande DESCRIBE USER. Assurez-vous que la propriété NAME ou EMAIL de l’utilisateur correspond à la valeur de la même propriété dans l’ID Entra pour l’utilisateur correspondant. Si vous utilisez le mappage des adresses e-mail, assurez-vous que l’adresse e-mail est unique pour tous les utilisateurs du compte Snowflake.

Rôle non répertorié dans le jeton d’accès ou filtré (code d’erreur 390317)¶

Cette erreur se produit lorsque Snowflake ne peut pas attribuer un rôle à l’utilisateur sur la base des informations contenues dans le jeton d’accès OAuth. Le jeton d’accès est configuré avec le champ d’application session:role-any, qui permet à l’utilisateur d’assumer n’importe lequel des rôles qui lui sont assignés dans Snowflake. Toutefois, l’intégration de sécurité doit être explicitement configurée pour autoriser ce comportement.

Utilisez la commande DESCRIBE SECURITY INTEGRATION pour vérifier la valeur de la propriété EXTERNAL_OAUTH_ANY_ROLE_MODE, puis remplacez-la par ENABLE ou 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';

Le rôle spécifié dans la chaîne de connexion n’est pas attribué à cet utilisateur (code d’erreur 390186)¶

Cette erreur se produit lorsque l’intégration de sécurité Snowflake n’autorise pas le rôle par défaut de l’utilisateur à utiliser l’intégration de sécurité.

Pour résoudre ce problème, vérifiez les propriétés suivantes dans la sortie de DESCRIBE SECURITY INTEGRATION :

• EXTERNAL_OAUTH_ALLOWED_ROLES_LIST : Si le paramètre est activé, vérifiez qu’il contient le rôle par défaut de l’utilisateur.

• EXTERNAL_OAUTH_BLOCKED_ROLES_LIST : Si le paramètre est activé, vérifiez qu’il ne contient pas le rôle par défaut de l’utilisateur.