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.

Exigences en matière d’approvisionnement des utilisateurs¶

Pour garantir une authentification réussie à l’aide de la configuration de mappage décrite précédemment, assurez-vous que les conditions suivantes sont remplies :

• Un mappage strict de un à un existe entre les utilisateurs Entra ID et les utilisateurs Snowflake. Désignez ou créez un utilisateur Snowflake pour chaque utilisateur Entra ID qui utilisera l’intégration.

• Chaque utilisateur Entra ID correspond à un seul utilisateur Snowflake. Pour le mappage des e-mails, l’e-mail principal Entra ID doit correspondre exactement à l’EMAIL_ADDRESS de l’utilisateur Snowflake. Pour le mappage UPN, le UPN Entra ID doit correspondre exactement au LOGIN_NAME de l’utilisateur.

Pour réduire l’effort d’administration manuelle, vous pouvez éventuellement configurer l’approvisionnement et le désapprovisionnement automatiques des utilisateurs à partir d’Entra ID vers Snowflake. Consultez Configurer l’approvisionnement automatique.

Créer et configurer les Agents Cortex¶

Après avoir créé l’intégration de sécurité, assurez-vous qu’au moins un objet d’Agent Cortex existe dans votre compte Snowflake pour l’intégration Teams ou Microsoft 365 Copilot à utiliser.

Si vous disposez déjà d’un agent fonctionnel que vous souhaitez utiliser, aucune action supplémentaire n’est requise pour cette étape.

Pour créer un nouvel agent, suivez les instructions.

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 en matière de contrôle d’accès de la rubrique Agents Cortex.

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 :doc:` SECONDARY ROLES </sql-reference/sql/use-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 = ('ALL');

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 approprié, puis sélectionnez Connect Snowflake account.

   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.

Une fois la configuration validée, l’application Teams est connectée à votre compte Snowflake et les agents sont prêts à être utilisés.

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, utilisez la commande DESCRIBE USER. 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.

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

Autorisations requises¶

Assurez-vous que le rôle sous lequel l’intégration sera exécutée (le rôle par défaut de chaque utilisateur ou les rôles secondaires autorisés) dispose des accords décrits dans la section Exigences en matière de contrôle d’accès.

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 Entra ID, qui est au format https://login.microsoftonline.com/tenant-id/v2.0, où tenant-id est l’ID client Microsoft de votre organisation.

• 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 l’ID client Microsoft de votre organisation.

• 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 Entra ID et l’enregistrement de l’utilisateur correspondant dans Snowflake, généralement car l’identité de l’utilisateur Entra ID ne correspond pas exactement à un utilisateur de Snowflake. Cela peut se produire lorsque l’utilisateur Snowflake n’existe pas, lorsque 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. Lors de l’utilisation du mappage d’adresses e-mail, chaque utilisateur du compte Snowflake qui utilisera l’intégration doit avoir une adresse e-mail unique.

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.