Cortex Agents für Microsoft Teams und Microsoft 365 Copilot¶

Erteilen der Zustimmung für den Prinzipal der OAuth-Ressource¶

So erteilen Sie die Zustimmung für den Dienstprinzipal der Anwendung für die OAuth-Ressource des Cortex Agents-Bots:

1. Navigieren Sie in Ihrem Browser zu https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=5a840489-78db-4a42-8772-47be9d833efe, wobei tenant-id die Microsoft-Mandanten-ID Ihrer Organisation ist.

   Wenn Sie noch nicht angemeldet sind, werden Sie aufgefordert, dies zu tun.

   Das Dialogfeld Permission requested mit der für die Anwendung erforderlichen Berechtigung wird angezeigt.

2. Wählen Sie Accept aus, um die angeforderte Berechtigung zu erteilen.

Erteilen der Zustimmung für den Prinzipal des OAuth-Clients¶

Dieser Prozess zeigt zwei Dialogfelder an. Beide ähneln dem für den Prinzipal der OAuth-Ressource, die angeforderten Berechtigungen unterscheiden sich jedoch.

So erteilen Sie die Zustimmung für den Dienstprinzipal der Anwendung für den Snowflake OAuth-Client des Cortex Agents Bots:

1. Navigieren Sie in Ihrem Browser zu https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=bfdfa2a2-bce5-4aee-ad3d-41ef70eb5086, wobei tenant-id die Microsoft-Mandanten-ID Ihrer Organisation ist.

   Das Dialogfeld Permissions requested (1 of 2) wird angezeigt, das einen Satz von Berechtigungen enthält, die für die Anwendung erforderlich ist.

2. Wählen Sie Accept aus, um die angeforderten Berechtigungen zu erteilen.

   Der zweite Dialogfeld für die Berechtigungen wird angezeigt (Permissions requested (2 of 2)).

3. Wählen Sie Accept aus, um die angeforderten Berechtigungen zu erteilen.

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

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.

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'

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.

Vorbereiten der Cortex-Agentendefinition¶

Sobald die Sicherheitsintegration konfiguriert ist, müssen Sie die Umgebung und die Definition des Agenten in Snowflake vorbereiten. Dies beinhaltet das Erstellen der erforderlichen Datenbankobjekte und das Definieren der Logik des Agenten in einem einzigen JSON-Objekt Die Definition legt die Anweisungen des Agenten, seine Tools (wie Cortex Analyst und Cortex Search) und die Ressourcen für diese Tools fest. Die Schemadefinition folgt dem Bodyschema der Cortex Agents API-Anforderung mit einigen Ergänzungen. Im Folgenden sehen Sie die allgemeine Struktur des JSON-Objekts:

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

Laden Sie die Agentendefinition in einen Snowflake-Stagingbereich hoch, und stellen Sie sicher, dass sie für alle Endbenutzer zugänglich ist, die den Agenten verwenden werden.

Sie können die Benutzererfahrung verbessern, indem Sie zwei optionale Felder für Suchergebnisse und Konversationshinweise festlegen:

• Suchanfragen können ein von Menschen lesbarer Titel und ein direkter Link zum Quelldokument bereitgestellt werden, indem in der Definition tool_resources des Suchtools zwei optionale Felder angegeben werden:

  • title_column ist eine Spalte, die den von Menschen lesbaren Titel eines Dokuments enthält.

  • id_column ist eine Spalte, die einen eindeutigen Bezeichner für das Dokument enthält, den Cortex Search verwendet, um einen Link zu dem Dokument zu erstellen.

• Es können Starter-Aufforderungen bereitgestellt werden, um Benutzer bei der Formulierung ihrer Fragen im Feld starter_prompts auf der obersten Ebene der Agentendefinition zu unterstützen.

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

  Copy

Gewähren der erforderlichen Berechtigungen für Endbenutzer¶

Damit Benutzer erfolgreich mit einem Cortex Agent in Teams interagieren können, muss ihre Snowflake-Standardrolle (oder eine andere bestimmte Rolle) über Berechtigungen für alle zugrunde liegenden Objekte verfügen:

• Alle Berechtigungen, die im Abschnitt „Anforderungen an die Zugriffssteuerung“ des Themas „Cortex Agents“ aufgeführt sind

• READ-Zugriff auf den Stagingbereich, der die JSON-Definition des Agenten enthält

• USAGE für das dem Agenten zugewiesene Warehouse

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.

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.

Zusammenfassend muss die Standardrolle jedes Benutzers in Snowflake über die erforderlichen Berechtigungen für den Zugriff auf die Objekte des Agenten verfügen, wie im Abschnitt „Anforderungen an die Zugriffssteuerung“ des Themas „Cortex Agents“ beschrieben, sowie über READ-Zugriff auf den Stagingbereich, der JSON-Definition des Agenten enthält, und USAGE für das Warehouse des Agenten. (Die Standardrolle des Benutzers wird durch die Einstellung DEFAULT_ROLE im Profil des Benutzers festgelegt).

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 den SECONDARY ROLES-Mechanismus wie folgt 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 = ('<integration_specific_role>');

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.

   Um diese URL 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.

   Bemerkung

   Möglicherweise wird eine Warnung angezeigt, die Sie anweist, sicherzustellen, dass die Sicherheitsintegration „Microsoft Identity Platform Access Token v2.0“ verwendet. Sie können diese Warnung ignorieren; das Format des Tokens für die Snowflake-Sicherheitsintegration ist kompatibel.

3. Nachdem diese Prüfung bestanden wurde, wird ein Formular angezeigt, das die folgenden Konfigurationsdetails anfragt:

   • Kontoalias: Ein benutzerfreundlicher Name für dieses Snowflake-Konto, der in der Teams-Schnittstelle angezeigt wird, z. B. „Verkaufsanalyse“.

   • Pfad der Agentendefinition: Der vollqualifizierte Pfad zur JSON-Definitionsdatei des Agenten in einem Snowflake-Stagingbereich im Format @stage_name/path_to_definition_file, z. B. @my_cortex_agents/my_agent.json.

   • Standard-Warehouse: Der Name des Snowflake-Warehouses, das der Agent für Abfragen verwendet.

   Geben Sie diese Informationen ein, und klicken Sie dann auf Finalize account configuration.

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

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 überprüfen, führen Sie den Befehl DESCRIBE USER auf, und überprüfen Sie die Eigenschaft DEFAULT_ROLE in der Ausgabe. Wenn die Standardrolle des Benutzers nicht korrekt ist, ändern Sie diese mit dem Befehl ALTER USER.

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

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. Um sicherzustellen, dass Sie keine sekundären Rollen entfernen, die dem Benutzer bereits zugewiesen sind, beachten Sie die Eigenschaft DEFAULT_SECONDARY_ROLES in der Ausgabe von DESCRIBE USER. Schließen Sie diese bereits vorhandenen Rollen ein, wenn Sie die integrationsspezifische Rolle hinzufügen.

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

Erforderliche Berechtigungen¶

Die Standardrolle des Benutzers (oder eine Standard-Sekundärrolle) muss die unten beschriebenen Berechtigungen besitzen.

• Cortex-AI-Funktionszugriff über die Rolle SNOWFLAKE.CORTEX_USER. Standardmäßig ist diese Rolle der Rolle PUBLIC zugewiesen, damit alle Benutzer auf Cortex-AI-Funktionen zugreifen können. Wenn Ihre Organisation SNOWFLAKE.CORTEX_USER aus PUBLIC entfernt hat, müssen Sie sie explizit der Rolle zuweisen, unter der der Agent ausgeführt wird.

• Wenn der Agent das Cortex Analyst-Tool verwendet, muss die Rolle außerdem über die folgenden Berechtigungen verfügen:

  • USAGE für alle Datenbanken und Schemas, auf die im semantischen Modell verwiesen wird

  • SELECT für alle Tabellen und Ansichten, auf die im semantischen Modell verwiesen wird

  • READ-Zugriff für den Stagingbereich, der die Datei(en) des semantischen Modells enthält

• Wenn der Agent einen Cortex Search Service verwendet, muss die Rolle über USAGE für den jeweils verwendeten Service verfügen.

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 :samp: 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 vorliegt, 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 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. Wenn Sie die Zuordnung von E-Mail-Adressen verwenden, müssen Sie sicherstellen, dass die E-Mail-Adresse für alle Benutzer des Snowflake-Kontos eindeutig ist.

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

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.