Freigeben über

Authentifizierung für KI-Agents

KI-Agents müssen sich häufig bei anderen Ressourcen authentifizieren, um Aufgaben auszuführen. Ein bereitgestellter Agent muss z. B. auf einen Vector Search-Index zugreifen, um unstrukturierte Daten abzufragen, einen Endpunkt, der ein Foundation-Modell aufruft, oder Unity-Katalogfunktionen zum Ausführen benutzerdefinierter Logik.

Diese Seite behandelt Authentifizierungsmethoden für Agents, die in Databricks-Apps bereitgestellt werden. Informationen zu Agents, die auf Model Serving-Endpunkten bereitgestellt werden, finden Sie unter Authentifizierung für KI-Agents (Model Serving).

Databricks-Apps bieten zwei Authentifizierungsmethoden für Agents. Jede Methode dient verschiedenen Anwendungsfällen:

Methode Description Wann verwenden
App-Autorisierung Der Agent authentifiziert sich mit einem automatisch erstellten Dienstprinzipal, der über konsistente Berechtigungen verfügt. Zuvor als Dienstprinzipalauthentifizierung bezeichnet. Der häufigste Anwendungsfall. Verwenden Sie dies, wenn alle Benutzer den gleichen Zugriff auf Ressourcen haben sollten.
Benutzerautorisierung Der Agent authentifiziert sich mithilfe der Identität des Benutzers, der die Anforderung stellt. Zuvor als On-Behalf-Of (OBO)-Authentifizierung bezeichnet. Verwenden Sie diese Möglichkeit, wenn Sie benutzerspezifische Berechtigungen, Überwachungspfade oder fein abgestimmte Zugriffssteuerung mit Unity-Katalog benötigen.

Sie können beide Methoden in einem einzigen Agent kombinieren. Verwenden Sie beispielsweise die App-Autorisierung, um auf einen freigegebenen Vektorsuchindex zuzugreifen, während die Benutzerautorisierung zum Abfragen von benutzerspezifischen Tabellen verwendet wird.

App-Autorisierung

Standardmäßig authentifizieren sich Databricks-Apps mithilfe der App-Autorisierung. Azure Databricks erstellt beim Erstellen der App automatisch einen Dienstprinzipal und dient als Identität der App.

Alle Benutzer, die mit der App interagieren, verwenden dieselben Berechtigungen, die für den Dienstprinzipal definiert sind. Dieses Modell eignet sich gut, wenn alle Benutzer dieselben Daten sehen sollen oder wenn die App freigegebene Vorgänge ausführt, die nicht an benutzerspezifische Zugriffssteuerungen gebunden sind.

Ausführliche Informationen zur App-Autorisierung finden Sie unter "App-Autorisierung".

Erteilen von Berechtigungen für das MLflow-Experiment

Ihr Agent benötigt Zugriff auf ein MLflow-Experiment, um Ablaufverfolgungen und Auswertungsergebnisse zu protokollieren.

Erteilen Sie dem Dienstprinzipal Can Edit die Berechtigung für das MLflow-Experiment:

  1. Klicken Sie auf der Startseite Ihrer App auf "Bearbeiten ".
  2. Navigieren Sie zum Schritt "Konfigurieren" .
  3. Fügen Sie im Abschnitt "App-Ressourcen " die MLflow-Experimentressource hinzu.

Siehe Hinzufügen einer MLflow-Experimentressource zu einer Databricks-App.

Erteilen von Berechtigungen für andere Databricks-Ressourcen

Wenn Ihr Agent andere Databricks-Ressourcen verwendet, z. B. Genie-Räume, Vector Search-Indizes oder SQL-Lagerhäuser, erteilen Sie den Dienstprinzipalberechtigungen über die Benutzeroberfläche von Databricks Apps. Eine vollständige Liste der unterstützten Ressourcen und Konfigurationsanweisungen finden Sie unter Hinzufügen von Ressourcen zu einer Databricks-App .

Um auf das Eingabeaufforderungsprotokoll zuzugreifen, erteilen Sie CREATE FUNCTION, EXECUTE und MANAGE Berechtigungen für das Unity Katalog-Schema zum Speichern von Eingabeaufforderungen.

In der folgenden Tabelle sind die Mindestberechtigungen aufgeführt, die für Agents für den Zugriff auf allgemeine Databricks-Ressourcen erforderlich sind:

Ressourcentyp Erlaubnis
SQL Warehouse Can Use
Endpunkt für Modellbereitstellung Can Query
Unity-Katalogfunktion CAN Execute
Genie Space Can Run
Vektorsuchindex Can Select
Unity-Katalogtabelle SELECT
Unity-Katalogverbindung Use Connection
Unity-Katalog-Volumen Can Read oder Can Read and Write
Lakebase Can Connect and Create

Wenn Sie Zugriff auf Unity-Katalogressourcen gewähren, müssen Sie auch Berechtigungen für alle nachgelagerten abhängigen Ressourcen erteilen. Wenn Sie z. B. Zugriff auf einen Genie-Bereich gewähren, müssen Sie auch den Zugriff auf die zugrunde liegenden Tabellen, SQL-Lagerhäuser und Unity-Katalogfunktionen gewähren.

Der Benutzer, der die Ressource hinzufügt, muss über die Berechtigung für die Can Manage Ressource und die App verfügen. Die vollständige Liste der unterstützten Ressourcen und alle verfügbaren Berechtigungen finden Sie unter unterstützten Ressourcentypen.

Bewährte Methoden zum sicheren Verwalten der App-Autorisierung, einschließlich der Verwaltung von Anmeldeinformationen und der Grundsätze der geringsten Berechtigungen, finden Sie unter App-Autorisierung.

Benutzerautorisierung

Von Bedeutung

Die Benutzerautorisierung befindet sich in der öffentlichen Vorschau. Ihr Arbeitsbereichsadministrator muss ihn aktivieren, bevor Sie die Benutzerautorisierung verwenden können.

Die Benutzerautorisierung ermöglicht es einem Agent, mit der Identität des Benutzers zu handeln, der die Anforderung vornimmt. Dies bietet Folgendes:

  • Benutzerspezifischer Zugriff auf vertrauliche Daten
  • Feinkörnige Datensteuerelemente, die durch den Unity Catalog durchgesetzt werden
  • Benutzerspezifische Prüfprotokolle
  • Automatisches Erzwingen von zeilenbasierten Filtern und Spaltenmasken.

Verwenden Sie die Benutzerautorisierung, wenn Ihr Agent auf Ressourcen zugreifen muss, indem Sie die Identität des anfordernden Benutzers anstelle des Dienstprinzipals der App verwenden.

Funktionsweise der Benutzerautorisierung

Wenn Sie die Benutzerautorisierung für Ihren Agent konfigurieren:

  1. Fügen Sie Ihrer App API-Bereiche hinzu: Definieren Sie, auf welche Databricks-APIs die App im Auftrag von Benutzern zugreifen kann. Siehe Hinzufügen von Bereichen zu einer App.
  2. Benutzeranmeldeinformationen werden eingeschränkt: Azure Databricks übernimmt die Anmeldeinformationen des Benutzers und schränkt sie auf die von Ihnen definierten API-Bereiche ein.
  3. Tokenweiterleitung: Das Downscoped-Token wird Ihrer App über den x-forwarded-access-token HTTP-Header zur Verfügung gestellt.
  4. MLflow AgentServer speichert das Token: Der Agentserver speichert dieses Token automatisch pro Anforderung für den bequemen Zugriff im Agentcode.

Konfigurieren Sie die Benutzerautorisierung, indem Sie Bereiche in der Benutzeroberfläche von Databricks Apps hinzufügen, wenn Sie Ihre App erstellen oder bearbeiten oder die API programmgesteuert verwenden. Ausführliche Anweisungen finden Sie unter Hinzufügen von Bereichen zu einer App .

Agents mit Benutzerautorisierung können auf die folgenden Databricks-Ressourcen zugreifen:

  • SQL Warehouse
  • Genie Space
  • Dateien und Verzeichnisse
  • Modellbereitstellungs-Endpunkt
  • Vektorsuchindex
  • Unity-Katalogverbindungen
  • Unity-Katalogtabellen

Implementieren der Benutzerautorisierung

Um die Benutzerautorisierung zu implementieren, müssen Sie Ihrer App Autorisierungsbereiche hinzufügen. Bereiche beschränken, was die App im Namen des Benutzers tun kann.

  1. Wechseln Sie in der Benutzeroberfläche von Databricks zu Ihren Databricks-Apps-Autorisierungseinstellungen.
  2. Klicken Sie auf "+Bereich hinzufügen", und wählen Sie die Bereiche aus, auf die Sie im Namen des Benutzers zugreifen möchten.
  3. Speichern Sie die Änderungen.

Um die Benutzerautorisierung in Ihrem Agentcode zu konfigurieren, rufen Sie den Header für diese Anforderung vom AgentServer ab, und erstellen Sie einen Arbeitsbereichsclient mit diesen Anmeldeinformationen.

  1. Importieren Sie im Agentcode das Authentifizierungshilfsprogramm:

    Wenn Sie eine der bereitgestellten Vorlagen aus databricks/app-templates verwenden, importieren Sie das bereitgestellte Hilfsprogramm:

    from databricks_app.utils import get_user_workspace_client

    Andernfalls importieren Sie aus den Agent-Server-Dienstprogrammen:

    from agent_server.utils import get_user_workspace_client

    Die get_user_workspace_client() Funktion verwendet den Agent-Server, um den x-forwarded-access-token Header zu erfassen und einen Arbeitsbereichsclient mit diesen Benutzeranmeldeinformationen zu erstellen und die Authentifizierung zwischen Dem Benutzer, der App und dem Agentserver zu verarbeiten.

  2. Initialisieren Sie den Arbeitsbereichsclient zur Abfragezeit, nicht während des App-Starts:

    Von Bedeutung

    Rufen Sie get_user_workspace_client() innerhalb der invoke und stream Handler auf, nicht in __init__ oder beim App-Start. Benutzeranmeldeinformationen sind nur zur Abfragezeit verfügbar, wenn ein Benutzer eine Anforderung sendet. Beim Initialisieren während des App-Starts tritt ein Fehler auf, da noch kein Benutzerkontext vorhanden ist.

    # In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Eine vollständige Anleitung zum Hinzufügen von Bereichen und Grundlegendes zur bereichsbasierten Sicherheit finden Sie unter Bereichsbasierte Sicherheits- und Berechtigungseskalation.

Authentifizieren bei den Databricks MCP-Servern

Um sich bei Databricks MCP-Servern zu authentifizieren, geben Sie alle Ressourcen an, die Ihr Agent in Ihrer databricks.yaml Datei benötigt. Gewähren Sie dem Dienstprinzipal der App (oder Benutzern, wenn die Benutzerautorisierung verwendet wird) Zugriff auf alle nachgelagerten Ressourcen.

Wenn Ihr Agent z. B. die unten aufgeführten MCP-Server-URLs verwendet, müssen Sie Zugriff auf alle Vektorsuchindizes in den prod.customer_support und prod.billing Schemata und alle Unity-Katalogfunktionen in prod.billing gewähren.

  • https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
  • https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
  • https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Konfigurieren der Authentifizierung mit Databricks-Objektpaketen

Sie können alle Authentifizierungseinstellungen programmgesteuert mithilfe von Databricks Asset Bundles anstelle der Benutzeroberfläche von Databricks Apps konfigurieren. Auf dieser Seite wird die uibasierte Konfiguration gezeigt, um zu veranschaulichen, welche Ressourcen und Berechtigungen erforderlich sind, aber dieselbe Konfiguration kann in Ihren Bündel-YAML-Dateien definiert werden. Die vollständige Konfigurationsreferenz für Bündel finden Sie unter "Apps in Bundles ".

Nächste Schritte

  • Last updated on