Cortex Agents für Microsoft Teams und Microsoft 365 Copilot

Einführung

Für die meisten Teams bedeutet der Zugriff auf aktuelle Dateneinblicke einen Kontextwechsel zwischen dedizierten Analyseplattformen und Kommunikationstools, was zu Verzögerungen und geringerer Produktivität führt. Die Integration eines agentenbasierten AI-Systems in Microsoft Teams kann die Antworten direkt dorthin bringen, wo Konversationen stattfinden und Entscheidungen getroffen werden, und so den Informationsfluss in Ihrem Unternehmen beschleunigen. Der Aufbau einer sicheren Analyselösung direkt im Chat, die sowohl leistungsfähig als auch intuitiv ist, ist jedoch ein beträchtliches Unterfangen. Glücklicherweise hat Snowflake eine Lösung für Sie erstellt.

Die Snowflake Cortex Agents-Integration für Microsoft Teams und Microsoft 365 Copilot bettet die konversationsfähigen AI-Agenten von Snowflake in Ihre Geschäftskommunikationsplattform ein. Geschäftsteams und technisch nicht versierte Benutzer können mit ihren strukturierten und unstrukturierten Snowflake-Daten über einfache, natürliche Sprache interagieren und direkte Antworten und Visualisierungen erhalten, ohne ihre Teams-Chats oder Microsoft 365 im weiteren Sinne verlassen zu müssen. Die Integration ist über Microsoft AppSource für eine nahtlose Bereitstellung verfügbar.

Wichtige Funktionen

  • Nahtlose Analysen über natürliche Sprache. Begeistern Sie die Geschäftsleitung bei Geschäftsentscheidungen mit sofortigen Einblicken über die Microsoft Teams- und Microsoft 365 Copilot-Schnittstellen. Sie können Trends ermitteln und Daten analysieren, ohne technische Kenntnisse aufweisen oder darauf warten zu müssen, dass ein kundenspezifisch Dashboard erstellt wird. Sie können im Konversationsstil Fragen stellen und erhalten umgehend genaue, LLM-gestützte Antworten in Text-, Tabellen- oder Diagrammform, was die datengesteuerte Entscheidungsfindung erheblich beschleunigt.

  • Doppelte Schnittstellen für umfassende Workflows. Cortex Agents für Microsoft Teams bieten zwei Schnittstellen für unterschiedliche Geschäftsanforderungen. Verwenden Sie die Standard-Teams-Anwendung für dedizierte, detaillierte Analysen innerhalb eines Teams-Bot-Anwendungschats oder den Microsoft 365 Copilot-Agenten, um gezielte Snowflake-Erkenntnisse in Ihren umfassenderen Konversations-Workflow innerhalb des Microsoft 365 Copilot-Ökosystems einzubringen.

  • Unterstützt von Snowflake Cortex Agents. Diese Integration wird von der Snowflake Cortex Agents-API unterstützt, die die Komplexität der Generierung genauer, zuverlässiger Erkenntnisse aus Ihren Daten bewältigt. Das agentenbasierte System interpretiert Benutzeranfragen und generiert Antworten auf intelligente Weise, sodass Ihre Teams keine komplexen dialogfähigen AI-Muster erstellen oder zugrunde liegende Modelle verwalten müssen. Sie können dieselben Agenten wiederverwenden, die Sie auch mit Snowflake Intelligence nutzen, um doppelten Konfigurations- und Governance-Aufwand zu vermeiden.

  • Sicherheit und Governance auf Unternehmensebene. Die Integration basiert auf dem datenschutzorientierten Fundament von Snowflake und stellt sicher, dass Sie AI-gesteuerte Anwendungsfälle sicher erkunden können. Dies bedeutet:

    • Ihre Daten bleiben innerhalb der Governance-Grenzen von Snowflake. Benutzer-Aufforderungen werden an die Cortex Agents-API gesendet, aber die zugrunde liegenden Daten, die zur Generierung einer Antwort abgefragt werden, verlassen niemals die sichere Umgebung von Snowflake. Der resultierende SQL-Abfrage wird innerhalb Ihres Snowflake-Warehouses ausgeführt.

    • Nahtlose Integration in die Datenschutz- und Governance-Features von Snowflake. Die Integration respektiert die rollenbasierte Zugriffssteuerung (RBAC) von Snowflake vollständig. Alle Abfragen, die im Namen eines Benutzers ausgeführt werden, halten sich an die festgelegten Berechtigungen und stellen sicher, dass Benutzer nur Daten sehen können, für die sie Zugriffsrechte haben.

Einrichten der Integration

Die Microsoft Teams-Integration von Cortex Agents ermöglicht es Organisationsadministratoren, mehrere Snowflake-Konten mit den Teams- und Copilot-Arbeitsbereichen in ihren Organisationen zu verbinden. Das Einrichten der Integration umfasst einige einfache Schritte, die im Folgenden zusammengefasst werden:

  1. Mandantenweite Einrichtung durch Azure-Administrator. Die Integration erfordert eine einmalige Einrichtung durch einen Microsoft Azure-Administrator, um die Zustimmung für die Snowflake-Anwendung innerhalb des Mandanten von Microsoft Entra ID (zuvor Azure Active Directory) zu erteilen. Dieser Schritt aktiviert die sichere OAuth 2.0-Authentifizierung für die Integration.

  2. Snowflake-Sicherheitsintegration. Nachdem der Azure-Administrator die mandantenweite Einrichtung abgeschlossen hat, muss ein Snowflake-Administrator eine Sicherheitsintegration für jedes einzelne Snowflake-Konto konfigurieren, das mit der Microsoft Teams- oder M365 Copilot-Anwendung verbunden werden soll. Dieser Schritt sorgt dafür, dass die Integration sicher auf die erforderlichen Daten in jedem Snowflake-Konto zugreifen kann.

  3. Verknüpfen von Konten mit dem Bot. Sobald die Sicherheitsintegration konfiguriert ist, kann der Snowflake-Administrator das Snowflake-Konto mit dem Microsoft Teams- oder M365 Copilot-Bot verknüpfen. Dieser Schritt ermöglicht dem Bot den Zugriff auf die Daten und Funktionen des Snowflake-Kontos, sodass Benutzer direkt innerhalb von Teams oder Copilot mit ihren Daten interagieren können.

Voraussetzungen

Bevor Sie mit der Integration beginnen, vergewissern Sie sich, dass Sie Folgendes festgelegt haben:

  • Administratorzugriff: Das Setup erfordert Administratorzugriff sowohl auf Snowflake als auch auf Ihrem Microsoft-Mandanten.

  • Snowflake-Kontoregion: Ihr Snowflake-Konto muss in der Azure-Region East US 2 gehostet werden. Für Snowflake ist geplant, dass in Zukunft weitere Regionen unterstützt werden.

  • Snowflake-Administratorberechtigungen: Ihr Snowflake-Benutzer muss Zugriff auf die Rolle ACCOUNTADMIN oder SECURITYADMIN haben. Diese Berechtigungen sind erforderlich, um das erforderliche Sicherheitsintegrationsobjekt in Ihrem Snowflake-Konto zu erstellen.

  • Microsoft-Administratorberechtigungen: Ihr Azure-Benutzer muss über globale Administratorberechtigungen (oder eine entsprechende Rolle) für Ihren Microsoft Entra ID-Mandanten verfügen. Diese Berechtigungen sind nötig, um die erforderliche mandantenweite Administratorzustimmung für die Anwendung zu erteilen.

  • Microsoft-Mandanten-ID: Sie benötigen die Microsoft-Mandanten-ID Ihrer Organisation, um die Snowflake -Sicherheitsintegration zu konfigurieren. Weitere Informationen zum Ermitteln der Mandaten-ID Ihrer Organisation finden Sie unter Abrufen von Abonnementen- und Mandaten-IDs im Azure-Portal.

  • Individuelle Benutzerkonten: Jeder Endbenutzer muss seine eigenen Microsoft- und Snowflake-Benutzerkonten haben.

  • Endbenutzer-Lizenz: Benutzer müssen über die entsprechenden Microsoft-Lizenzen verfügen, um auf Microsoft Teams zugreifen zu können. Darüber hinaus ist eine Copilot-Lizenz erforderlich, wenn Sie die Integration in Microsoft 365 Copilot verwenden möchten.

Schritt 1: Mandantenweite Entra ID-Konfiguration

Um eine sichere Authentifizierung für Cortex Agents zu ermöglichen, muss ein Microsoft Azure-Administrator die Zustimmung für zwei im Snowflake-Mandanten gehostete Anwendungen erteilen und für jede Anwendung innerhalb Ihres Entra ID-Mandanten einen Dienstprinzipal erstellen. Die beiden Anwendungen sind:

  • OAuth-Ressource für Cortex Agents Bot: Repräsentiert die geschützte Snowflake-API und definiert die Zugriffsberechtigungen (Bereiche) für Clientanwendungen.

  • ** Snowflake-OAuth-Client für Cortex Agents-Bot:** Repräsentiert die Clientanwendung, in diesem Fall den Back-End-Dienst der Teams-Anwendung, der nach der Anforderung eines Zugriffstokens die Snowflake-API aufruft.

Anweisungen zum Erteilen der Zustimmung für diese Anwendungen finden Sie weiter unten. Der Prozess ist für beide Anwendungen sehr ähnlich, aber die spezifischen Berechtigungen und Geltungsbereiche unterscheiden sich leicht.

Bestätigen der erteilten Berechtigungen

Nachdem Sie die Zustimmung für beide Anwendungen erteilt haben, können Sie bestätigen, dass die Berechtigungen erfolgreich erteilt wurden, indem Sie den Abschnitt Enterprise applications im Microsoft Entra ID-Portal überprüfen.

  1. Melden Sie sich ggf. beim Microsoft Entra Admin Center an.

  2. Navigieren Sie zu den Unternehmensanwendungen, indem Sie „Unternehmensanwendungen“ in das Suchfeld eingeben und dann Enterprise applications in den Ergebnissen auswählen.

  3. Suchen Sie in der Liste All applications nach den beiden Anwendungen, für die Sie gerade Zustimmung erteilt haben: OAuth-Ressource des Snowflake Cortex Agents-Bots und OAuth-Client des Snowflake Cortex Agents-Bots Eine einfache Möglichkeit hierfür ist die Suche nach „Snowflake Cortex Agent“.

    Wenn beide Anwendungen in der Liste angezeigt werden, wurden die Berechtigungen korrekt erteilt. Wenn eine oder beide Anwendungen fehlen, versuchen Sie erneut, die Zustimmung zu erteilen.

Schritt 2: Snowflake-Sicherheitsintegration

Die Integration von Snowflake in Microsoft Teams erfordert eine Sicherheitsintegration, die kryptografisches Vertrauen zwischen Ihrem Snowflake-Konto und Ihrem Entra ID-Mandanten herstellt. Dieser Prozess erfordert Folgendes:

  • Aktivieren von Entra ID als externen OAuth-Anbieter in Snowflake.

  • Auswahl oder Erstellung mindestens eines Cortex Agent-Objekts für die Integration.

  • Zuweisen der erforderlichen Rollen und Berechtigungen, damit die vorgesehenen Benutzer den Agenten aufrufen können.

Aktivieren von Entra ID als externen OAuth-Anbieter

Ein Snowflake-Sicherheitsintegrationsobjekt stellt eine Integration mit einem externen OAuth-Anbieter dar, in diesem Fall Microsoft Entra ID. Diese Integration ermöglicht es Snowflake, Benutzer zu authentifizieren, die bei Microsoft Teams oder Copilot angemeldet sind.

Die folgenden SQL-Anweisung ist eine kommentierte Vorlage für die Erstellung der Integration. Dieser Befehl muss von einer Rolle mit ACCOUNTADMIN-Berechtigungen ausgeführt werden. Ersetzen Sie den tenant-id-Platzhalter mit Ihrer Microsoft Mandanten-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'
Copy

Eine vollständige Referenz der für diesen Befehl verfügbaren Parameter finden Sie unter CREATE SECURITY INTEGRATION (External OAuth).

Zusammen verknüpfen die Parameter EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM und EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE eine Entra ID-Identität mit einer Snowflake-Identität. Damit die Authentifizierung erfolgreich ist, muss der Wert des angegebenen Anspruchs im JWT genau mit dem Wert des angegebenen Attributs eines Benutzerobjekts in Snowflake übereinstimmen. Die beiden von Snowflake empfohlenen Hauptkonfigurationen sind:

  • Zuordnung anhand des Benutzerprinzipalnamens (User Principal Name, UPN): Stellen Sie den Parameter EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM auf „upn“ und den Parameter EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE auf „LOGIN_NAME“ ein.

  • Zuordnung anhand der E-Mail-Adresse: Stellen Sie den Parameter EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM auf „email“ und den Parameter EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE auf „EMAIL_ADDRESS“ ein.

Die obige Beispielanweisung verwendet die Konfiguration im Rahmen der Zuordnung anhand der E-Mail-Adresse, gibt aber auch UPN im Parameter EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM an, sodass Sie die Zuordnungsmethode ändern können, indem Sie nur EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE ändern.

Die Beispielanweisung aktiviert auch EXTERNAL_OAUTH_ANY_ROLE_MODE, sodass die Standardrolle des Benutzers verwendet wird.

Weitere Informationen zu OAuth-Bereiche finden Sie unter Bereiche.

Anforderungen an die Benutzerbereitstellung

Um eine erfolgreiche Authentifizierung mit der zuvor beschriebenen Zuordnung sicherzustellen, müssen die folgenden Anforderungen erfüllt sein:

  • Zwischen Entra ID- und Snowflake-Benutzern besteht eine strenge Eins-zu-Eins-Zuordnung. Benennen oder erstellen Sie einen Snowflake-Benutzer für jeden Entra ID-Benutzer, der die Integration verwenden wird.

  • Jeder Entra ID-Benutzer ist genau einem Snowflake-Benutzer zugeordnet. Für die E-Mail Zuordnung muss die primäre Entra ID-E-Mail-Adresse genau mit der EMAIL_ADDRESS des Snowflake-Benutzers übereinstimmen. Für die UPN-Zuordnung muss die Entra ID-UPN exakt mit dem LOGIN_NAME des Snowflake-Benutzers übereinstimmen.

Um den manuellen Verwaltungsaufwand zu reduzieren, können Sie optional die automatische Benutzerbereitstellung und -entfernung von Entra ID zu Snowflake konfigurieren. Informationen dazu erhalten Sie unter Automatische Bereitstellung konfigurieren.

Cortex Agents erstellen und konfigurieren

Nachdem Sie die Sicherheitsintegration erstellt haben, vergewissern Sie sich, dass mindestens ein Cortex Agent-Objekt in Ihrem Snowflake-Konto für die zu verwendende Teams- oder Microsoft 365 Copilot-Integration vorhanden ist.

Wenn Sie bereits einen funktionierenden Agenten haben, den Sie verwenden möchten, ist für diesen Schritt keine weitere Aktion erforderlich.

Wenn Sie einen neuen Agenten erstellen möchten, folgen Sie der Anleitung.

Bemerkung

Wenn Sie Snowflake Intelligence bereits verwenden und Agenten für diese Umgebung erstellt haben, können Sie diese Agenten mit der Microsoft Teams- und Microsoft 365 Copilot-Integration wiederverwenden. Sie müssen sie nicht neu erstellen oder neu konfigurieren. Alle Änderungen, die Sie an einem Agenten vornehmen (z. B. Anweisungen, Tools, zugrunde liegende Objekte oder Berechtigungen), werden sofort für alle drei Schnittstellen übernommen.

Erforderliche Berechtigungen für Benutzer erteilen

Stellen Sie sicher, dass die Rolle, unter der die Integration ausgeführt wird (die Standardrolle des jeweiligen Benutzers oder die zulässigen Sekundärrollen), über die unter Anforderungen an die Zugriffssteuerung beschriebenen Berechtigungen verfügt.

Schritt 3: Einrichten der Teams-App und Verbinden Ihres Snowflake-Kontos

Der letzte Schritt des Integrationsprozesses besteht darin, die Microsoft Teams-Anwendung einzurichten und sie mit den Snowflake-Benutzern zu verbinden, die sie verwenden werden. Dazu müssen Sie die folgenden Aufgaben erledigen:

  • Installieren Sie die Cortex Agents-App aus dem Teams Store

  • Verbinden Sie Ihr Snowflake-Konto mit der Teams-Anwendung

Installieren Sie die App aus dem Teams Store

Alle Benutzer müssen die Cortex Agents-App aus dem Microsoft Teams Store installieren. Um die App zu installieren, suchen Sie im Teams App Store nach „Snowflake Cortex Agents“ und klicken Sie dann auf Add, um die App zu installieren.

Bemerkung

Abhängig von den Microsoft Teams-Richtlinien Ihrer Organisation muss ein Teams-Administrator die App möglicherweise genehmigen, bevor sie für Benutzer verfügbar ist. Entsprechende Anweisungen finden Sie unter `Übersicht über die App-Verwaltung und -Governance im Teams Admin Center<https://learn.microsoft.com/en-us/microsoftteams/manage-apps>`_.

Verbinden Ihres Snowflake-Kontos mit der Teams-App

Der erste Benutzer, der mit der Cortex Agents-App in Teams interagiert, wird aufgefordert, sein Snowflake-Konto mit der App zu verbinden. Dieser Benutzer muss die Rolle ACCOUNTADMIN oder SECURITYADMIN in Snowflake haben, damit dieser Schritt erfolgreich ist.

Um es noch einmal zusammenzufassen: Die Standardrolle jedes Benutzers in Snowflake muss über die erforderlichen Berechtigungen für den Zugriff auf die Objekte des Agenten verfügen, wie im Abschnitt Anforderungen an die Zugriffssteuerung des Themas zu Cortex Agents beschrieben.

Sicherheitsintegrationen blockieren standardmäßig die wichtigsten Verwaltungsrollen von Snowflake. Daher können Sie keine administrativen Rollen wie ACCOUNTADMIN als Standardrolle für den Benutzer verwenden, der den Teams-Bot einrichten wird. Informationen zu dieser Einschränkung finden Sie unter BLOCKED_ROLES_LIST im Thema CREATE SECURITY INTEGRATION.

Snowflake empfiehlt, eine dedizierte, nicht administrative Rolle mit den erforderlichen Berechtigungen zu erstellen und diese als Standard für den Setup-Benutzer festzulegen. Alternativ können Sie auch wie folgt die :doc:` SECONDARY ROLES </sql-reference/sql/use-secondary-roles>` verwenden, um die zusätzlichen Berechtigungen zu erteilen, ohne die primäre Standardrolle des Benutzers zu ändern:

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

Um den Teams-Bot einzurichten, gehen Sie wie folgt vor:

  1. Klicken Sie auf I’m the Snowflake administrator unter dem Hinweis, dass ein Administrator Snowflake für Teams konfigurieren muss, um den Prozess zu starten.

  2. Geben Sie die URL Ihres Snowflake-Kontos an der angegebenen Stelle ein, und wählen Sie Connect Snowflake account aus.

    Um die URL Ihres Kontos zu finden, melden Sie sich bei Snowsight an, und klicken Sie in der linken unteren Ecke der Seite auf die Kontoauswahl. Der Hostname-Teil der URL wird oben im Menü angezeigt und hat das Format your-organization-your-account. Die vollständige URL ist your-organization-your-account.snowflakecomputing.com.

    Der Konfigurationsassistent überprüft, ob die URL zu einer gültigen Snowflake-Instanz in der Azure-Region US East 2 führt und bestätigt, dass Ihr Benutzer Zugriff darauf hat und über die erforderlichen Administratorberechtigungen verfügt.

Nachdem das Setup die letzte Prüfung bestanden hat, wird die Teams-App mit Ihrem Snowflake-Konto verbunden und die Agents sind einsatzbereit.

Tipp

Nachdem Sie Ihr Snowflake-Konto mit der Cortex Teams-App verbunden haben, können Sie weitere Snowflake-Konten mit derselben App verbinden, indem Sie sich bei der Teams-App mit einem Benutzer anmelden, der über die erforderlichen Berechtigungen verfügt, und den Befehl „Neues Konto hinzufügen“ im Chat ausführen.

Verwenden von Cortex Agents

Nachdem die Integration eingerichtet wurde, wird der Bot in der Microsoft Teams-Schnittstelle angezeigt und ermöglicht Ihren Benutzern, in einem privaten Chat mit ihm zu interagieren. Benutzer können Fragen in natürlicher Sprache stellen – und der Bot liefert Antworten, die auf Snowflake-Daten basieren.

In Microsoft 365 Copilot können Ihre Benutzer mit dem Agenten im Rahmen ihrer umfassenderen Workflows interagieren, Fragen stellen und Antworten zu ihren Snowflake-Daten über die Copilot-Schnittstelle erhalten.

Feedback zu Antworten (nur Teams)

Benutzer können direkt über die Microsoft Teams- Schnittstelle qualitatives Feedback zu den Antworten des Agenten geben (zum Beispiel, indem sie eine Antwort als hilfreich oder nicht hilfreich markieren und optional einen Kommentar hinzufügen). Benutzer können auch das zuvor abgegebene Feedback überprüfen. Eine Anweisung dazu finden Sie unter Benutzerfeedback für Agenten anzeigen.

Bemerkung

Die Feedback-Funktion ist nur in Microsoft Teams verfügbar und wird von der Microsoft 365 Copilot-Erfahrung nicht unterstützt.

Wechseln zwischen Konten und Agenten

Sie können mehrere Snowflake-Konten mit der Integration verbinden. Jedes verbundene Konto kann einen oder mehrere Cortex Agents zur Verfügung stellen. Sobald die Konten verbunden sind, können Benutzer zwischen Konten und Agenten auf der Teams-UI mit einem einzigen Klick wechseln, das heißt, sie müssen sich weder erneut authentifizieren noch die Verbindungsdetails erneut eingeben. Der Wechsel zwischen Konten und Agenten erleichtert den Vergleich von Erkenntnissen über verschiedene Geschäftsbereiche hinweg (z. B. Vertrieb vs. Marketing) unter Beibehaltung des Sicherheitskontexts der einzelnen Benutzer.

Tipp

Wenn Sie eine Befehlsinteraktion anstelle der UI bevorzugen, können Sie auch konversationsbezogen zwischen den Agenten eines Kontos wechseln (z. B. durch Eingabe von „Agent auswählen“).

Sicherheitshinweise

Die Cortex Agents-Integration für Microsoft Teams wurde unter Berücksichtigung der Sicherheit entwickelt und nutzt die vorhandenen Sicherheitsfeatures von Snowflake und die Authentifizierungsfunktionen von Microsoft Entra ID. Die Integration sorgt dafür, dass die Daten der Benutzer sicher bleiben und der Zugriff durch das rollenbasierte Zugriffssteuerungssystem (RBAC-System) gesteuert wird.

End-to-End-Authentifizierungsablauf

Um die Sicherheitsauswirkungen der Verwendung der Cortex Agents-Integration für Microsoft Teams zu verstehen, ist es wichtig, den End-to-End-Authentifizierungsablauf zu verstehen. Dieser Prozess umfasst die folgenden Schritte:

  • Benutzerinteraktion: Ein Benutzer sendet eine -Nachricht an den Snowflake Cortex Agents-Bot in Microsoft Teams.

  • Authentifizierungstrigger: Der Backend-Dienst des Bots (die „Client“-App) initiiert einen OAuth 2.0-Ablauf, der den Benutzer zu Microsoft Entra ID umleitet.

  • Benutzerauthentifizierung: Der Benutzer meldet sich bei seinem Microsoft-Konto mit seinen Unternehmensanmeldeinformationen an und erfüllt alle MFA-Richtlinien oder Richtlinien für bedingten Zugriff, die von ihrem Mandanten erzwungen werden.

  • Token-Ausgabe: Entra ID bietet einen kurzlebigen Autorisierungscode. Das Backend des Bots tauscht diesen Code sicher gegen ein JWT-Zugriffstoken aus.

  • API-Aufruf an Snowflake: Das Backend des Bots ruft die Snowflake Cortex Agents API auf, einschließlich des Zugriffstokens im Authorization: Bearer-Header.

  • Snowflake Token-Validierung: Der Snowflake-Dienst empfängt die Anfrage und validiert das JWT gegen die im Snowflake -Sicherheitsintegrationsobjekt definierte Richtlinie.

Rollenbasierte Zugriffssteuerung

Weil sie die Cortex Agents API unter einer bestimmten Benutzerrolle verwendet, führt die Teams-Integration Cortex Agents -Anfragen mit den genauen Berechtigungen der angegebenen Snowflake-Rolle des Benutzers aus. Der Agent erbt alle vorhandenen Data Governance-Steuerungsmechanismen, einschließlich:

  • Rollenbasierte Zugriffssteuerung: Der Agent kann nur auf Datenbanken, Schemas, Tabellen und Warehouses zugreifen, deren Verwendung die Benutzerrolle erlaubt.

  • Datenmaskierungsrichtlinien: Der Agent respektiert dynamische Datenmaskierungsrichtlinien und gewährt nur Zugriff, wenn die Rolle des Benutzers dies erlaubt.

  • Zugriffsrichtlinien auf Zeilenebene: Der Agent setzt Sicherheitsrichtlinien auf Zeilenebene durch.

Der Agent kann keine bestehenden Snowflake-Sicherheitskontrollen umgehen, und Benutzer können nicht auf Daten zugreifen, für die sie nicht bereits eine Zugriffsberechtigung haben.

Aktuelle Einschränkungen

OAuth-Identitätsanbieter muss Entra ID sein

Die Integration unterstützt ausschließlich Microsoft Entra ID als Identitätsanbieter für die Authentifizierung und benötigt eine direkte Eins-zu-Eins-Zuordnung zwischen Entra ID- und Snowflake-Benutzern. Organisationen, die einen anderen primären IdP verwenden (z. B. Okta oder einen anderen SAML/OIDC-Anbieter), können diese Integration aktivieren, indem sie den Standard-Identitätsverbund zwischen diesem Anbieter und Microsoft Entra ID konfigurieren. Bei diesem Verbundmodell verarbeitet der primäre IdP die Anmeldung des Benutzers, wonach Entra ID das endgültige von der Integration benötigte Token ausgibt.

Abhängigkeit der Standardbenutzerrolle

Die Funktionalität der Integration ist aufgrund einer architektonischen Einschränkung in der Cortex Agents API an die Standard-Snowflake-Rolle jedes Benutzers gebunden. Diese bestimmt die Sitzungsberechtigungen basierend auf dem während der Authentifizierung festgelegten Rollenkontext. Daher müssen der Standardrolle des Benutzers alle erforderlichen Berechtigungen für die zugrunde liegenden Objekte erteilt werden, damit der Agent korrekt funktioniert. Während das Feature SECONDARY ROLES von Snowflake dazu beitragen kann, den Datenzugriff zu erweitern, wird der primäre Ausführungskontext durch die Standardrolle des Benutzers bestimmt.

Problembehandlung

Wenn Sie Probleme mit der Integration von Cortex Agents für Microsoft Teams haben, finden Sie in den folgenden Abschnitten mögliche Lösungen.

Probleme mit Berechtigungen und Zugriff

Die Standardrolle des Benutzers muss über die erforderlichen Berechtigungen verfügen, um auf die Objekte zuzugreifen, die der Agent verwendet oder auf die er zugreift. Fehlermeldungen, die durch Zugriffsprobleme verursacht werden, enthalten normalerweise den Satz „Datenbankobjekt existiert nicht oder ist nicht autorisiert“.

Um derartige Probleme zu beheben, müssen Sie überprüfen, ob die Standardrolle des Benutzers auf eine Rolle festgelegt ist, die über die erforderlichen Berechtigungen verfügt.

Einstellung der Standardrolle

Der erste Schritt zur Behebung von Zugriffsproblemen besteht darin, die Einstellung der Standardrolle des Benutzers zu überprüfen. Um diese Einstellung zu verifizieren, verwenden Sie den Befehl DESCRIBE USER. Überprüfen Sie die Eigenschaft DEFAULT_ROLE in der Ausgabe. Wenn die Standardrolle des Benutzers nicht korrekt ist, ändern Sie sie mit dem Befehl ALTER USER.

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

Wenn das Ändern der primären DEFAULT_ROLE nicht möglich ist, können Sie den Sekundärrollen-Mechanismus von Snowflake verwenden. Ein Benutzer kann -Aktionen mit den kombinierten Berechtigungen seiner Primärrolle und seiner aktiven Sekundärrollen ausführen. So können Sie dem Benutzer eine zusätzliche, integrationsspezifische Rolle zuweisen, ohne seine Primärrolle zu ändern.

Um eine Sekundärrolle für die Cortex Agents-Integration hinzuzufügen, verwenden Sie SQL-Befehle wie die folgenden.

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

Erforderliche Berechtigungen

Stellen Sie sicher, dass die Rolle, unter der die Integration ausgeführt wird (die Standardrolle des jeweiligen Benutzers oder die zulässigen Sekundärrollen), über die unter Anforderungen an die Zugriffssteuerung beschriebenen Berechtigungen verfügt.

Probleme bei der Sicherheitsintegration

Eine Snowflake -Sicherheitsintegration verbindet den Microsoft Entra ID-Mandanten mit dem Snowflake-Konto. Die Probleme in diesem Abschnitt beziehen sich auf die Sicherheitsintegration.

Ungültiges OAuth-Zugriffstoken (Fehlercode 390303)

Dieser Fehler kann darauf hinweisen, dass ein oder mehrere Eigenschaftswerte in der Sicherheitsintegration falsch sind, sodass Snowflake das von Entra ID erhaltene Zugriffstoken nicht validieren kann. Um dies zu korrigieren, überprüfen Sie die folgenden Felder in der Sicherheitsintegration. Stellen Sie insbesondere sicher, dass die Mandanten-ID in den URLs korrekt ist.

  • EXTERNAL_OAUTH_ISSUER: Der Wert muss auf die korrekte URL des Entra ID-Ausstellers eingestellt sein, die im Format https://login.microsoftonline.com/tenant-id/v2.0 vorliegt, wobei tenant-id die Microsoft-Mandanten-ID Ihrer Organisation ist.

  • EXTERNAL_OAUTH_JWS_KEYS_URL: Der Wert muss auf die korrekte URL der JWS-Schlüssel eingestellt sein, die im Format https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys vorliegen, wobei tenant-id die Microsoft-Mandanten-ID Ihrer Organisation ist.

  • EXTERNAL_OAUTH_AUDIENCE_LIST: Dieser Wert muss die korrekte Zielgruppe für die Anwendung für die OAuth-Ressource des Cortex Agents Bots enthalten, welches die Anwendungs-ID 5a840489-78db-4a42-8772-47be9d833efe ist.

Aktualisieren Sie fehlerhafte Werte mit dem Befehl ALTER SECURITY INTEGRATION.

Falscher Benutzername oder Kennwort (Fehlercode 390304)

Diese Fehlermeldung weist auf eine Nichtübereinstimmung zwischen der von Entra ID gesendeten Benutzerkennung und dem entsprechenden Benutzerdatensatz in Snowflake hin. Dies liegt normalerweise daran, dass die Entra ID-Benutzeridentität nicht genau einem Snowflake-Benutzer zugeordnet ist. Dies kann passieren, wenn der Snowflake-Benutzer nicht existiert oder die zugeordnete UPN oder E-Mail-Adresse falsch ist oder wenn die Zuordnung für mehrere Snowflake-Benutzer aufgelöst wird (z. B. wenn die Zuordnung mithilfe einer E-Mail-Adresse erfolgt und mehrere Benutzer dieselbe Adresse verwenden).

Die Fehlermeldung enthält den UPN und die E-Mail-Adresse des Benutzers, der versucht, sich anzumelden. Verwenden Sie diese Informationen, um die Konfiguration des betroffenen Benutzers mithilfe des Befehls DESCRIBE USER zu überprüfen. Stellen Sie sicher, dass die Eigenschaft NAME oder EMAIL des Benutzers mit dem Wert der gleichen Eigenschaft in Entra ID für den entsprechenden Benutzer übereinstimmt. Bei Verwendung der E-Mail-Zuordnung muss jeder Benutzer im Snowflake-Konto, der die Integration verwenden soll, eine eindeutige E-Mail-Adresse haben.

Rolle nicht im Zugriffstoken aufgeführt oder wurde herausgefiltert (Fehlercode 390317)

Dieser Fehler tritt auf, wenn Snowflake dem Benutzer anhand der Informationen im OAuth-Zugriffstoken keine Rolle zuweisen kann. Das Zugriffstoken ist mit dem Bereich session:role-any konfiguriert, der es dem Benutzer ermöglicht, jede der ihm zugeordneten Rollen in Snowflake zu übernehmen. Die Sicherheitsintegration muss jedoch explizit so konfiguriert werden, dass sie dieses Verhalten zulässt.

Verwenden Sie den Befehl DESCRIBE SECURITY INTEGRATION, um den Wert der Eigenschaft EXTERNAL_OAUTH_ANY_ROLE_MODE zu überprüfen, und ändern Sie den Wert dann in ENABLE oder 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';
Copy

Die in der Verbindungszeichenfolge angegebene Rolle ist diesem Benutzer nicht zugewiesen (Fehlercode 390186)

Dieser Fehler tritt auf, wenn die Snowflake-Sicherheitsintegration der Standardrolle des Benutzers die Verwendung der Sicherheitsintegration nicht erlaubt.

Um dies zu beheben, überprüfen Sie die folgenden Eigenschaften in der Ausgabe von DESCRIBE SECURITY INTEGRATION:

  • EXTERNAL_OAUTH_ALLOWED_ROLES_LIST: Wenn der Parameter aktiviert ist, stellen Sie sicher, dass er die Standardrolle des Benutzers enthält.

  • EXTERNAL_OAUTH_BLOCKED_ROLES_LIST: Wenn der Parameter aktiviert ist, stellen Sie sicher, dass er nicht die Standardrolle des Benutzers enthält.

Sprache: Deutsch