Herstellen einer Verbindung mit einer API Databricks-App mithilfe der Tokenauthentifizierung

Sie können eine Databricks-App aufrufen, die eine HTTP-API (z. B. eine FastAPI- oder Gradio-App) mithilfe der OAuth 2.0 Bearer-Tokenauthentifizierung verfügbar macht. Diese Methode funktioniert aus Ihrer lokalen Entwicklungsumgebung, externen Anwendungen und anderen Azure Databricks-Apps.

Anforderungen

Um eine Verbindung mit einer Databricks-App mithilfe der Tokenauthentifizierung herzustellen, müssen Sie die folgenden Anforderungen erfüllen:

• Die App muss mindestens einen API-Endpunkt verfügbar machen, auf den über /api/ Routen zugegriffen werden kann.
• Sie müssen über CAN USE Berechtigung für die App verfügen. Siehe Konfigurieren von Berechtigungen für eine Databricks-App.
• Sie müssen ein Azure Databricks Zugriffstoken mithilfe einer der unterstützten Authentifizierungsmethoden generieren können.

Authentifizierungsmethoden

Wählen Sie die Authentifizierungsmethode aus, die Ihrem Verbindungsszenario entspricht:

Lokale Entwicklung

Verwenden Sie zum Herstellen einer Verbindung aus Ihrer lokalen Entwicklungsumgebung die Databricks CLI oder SDKs mit Ihren Benutzeranmeldeinformationen.

1. Melden Sie sich mit der CLI an:

   databricks auth login --host https://<workspace-url> --profile my-env
   

   Azure Databricks empfiehlt die Verwendung der OAuth-Benutzer-zu-Maschine-Authentifizierung (U2M).

2. Generieren eines Zugriffstokens:

   Befehlszeilenschnittstelle (CLI)

   databricks auth token --profile my-env
   

   Python

   from databricks.sdk.core import Config
   config = Config(profile="my-env")
   token = config.oauth_token().access_token
   

Externe Anwendungen

Verwenden Sie für den programmgesteuerten Zugriff von externen Anwendungen die Dienstprinzipalauthentifizierung mit Computer-zu-Computer-Anmeldeinformationen .For programmatic access from external applications, use service principal authentication with machine-to-machine (M2M) credentials. Siehe Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.

1. Erstellen Sie einen Dienstprinzipal, und rufen Sie die Client-ID und den geheimen Schlüssel ab. Siehe Dienstprinzipale.

2. Generieren Sie ein Zugriffstoken mithilfe des Databricks SDK:

   from databricks.sdk import WorkspaceClient
   import requests
   
   # Option 1: Explicit credentials
   wc = WorkspaceClient(
       host="https://<workspace-url>",
       client_id="<service-principal-client-id>",
       client_secret="<service-principal-client-secret>"
   )
   
   # Option 2: Environment variables
   # Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
   wc = WorkspaceClient()
   
   # Generate Bearer token
   headers = wc.config.authenticate()
   

Aus anderen Databricks-Apps

Wenn Sie eine Verbindung von einer Databricks-App zu einer anderen herstellen, bearbeitet die App die Authentifizierung automatisch mithilfe des zugewiesenen Dienstprinzipals.

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

Aus einem Azure Databricks-Notizbuch

Um eine App-API aus einem Azure Databricks-Notizbuch aufzurufen, müssen Sie das interne Token des Notizbuchs für ein OAuth-Token mit Zielgruppenbereich austauschen und dann dieses Token verwenden, um die App abzufragen.

1. Rufen Sie die OAuth-Client-ID der App ab. Rufen Sie die ID mit dem Azure Databricks SDK ab:

   from databricks.sdk import WorkspaceClient
   
   w = WorkspaceClient()
   app_client_id = w.apps.get("<app-name>").oauth2_app_client_id
   

2. Tausche das Notebook-Token gegen ein zugriffsbereichspezifisches Zugriffstoken für die Zielgruppe aus.

   import requests
   
   url = "https://<workspace-url>/oidc/v1/token"
   notebook_token = (
       dbutils.notebook.entry_point.getDbutils()
       .notebook().getContext().apiToken().get()
   )
   
   data = {
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token": notebook_token,
       "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "all-apis",
       "audience": app_client_id,
   }
   
   response = requests.post(url=url, data=data)
   audience_token = response.json()["access_token"]
   

3. Verwenden Sie das audience_token Bearer-Token, um Ihre App aufzurufen. Beispiele finden Sie unter Senden von Anforderungen an die App.

Angeben von OAuth-Bereichen für die Benutzerautorisierung

Wenn Ihre App die Benutzerautorisierung verwendet, muss Ihr Zugriffstoken Bereiche enthalten, die eine Obermenge der für die App konfigurierten Bereiche sind. Wenn das Token nicht über die erforderlichen Bereiche verfügt, können Anforderungen mit 401- oder 403-Fehlern fehlschlagen.

Ein token, das mit der Databricks CLI generiert wird, enthält standardmäßig den all-apis Bereich, der die Benutzerautorisierungsanforderungen für jede App erfüllt:

databricks auth token --profile my-env

Zum Anfordern bestimmter Bereiche anstelle von all-apis, können Sie manuell ein Zugriffstoken mit expliziten Bereichen mithilfe eines benutzerdefinierten OAuth-Flusses anfordern. Die folgende Anforderung fordert z. B. explizit ein Zugriffstoken mit den sql, file.files, und dashboards.genie Bereichen an:

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

Vollständige Anweisungen finden Sie unter Manuelles Generieren von OAuth U2M-Zugriffstoken.

Senden von Anforderungen an die App

Wenn Sie die API-Endpunkte Ihrer App aufrufen, schließen Sie das Bearer-Token in den Autorisierungsheader ein, und ersetzen <your-endpoint> Sie ihn durch den tatsächlichen API-Pfad Ihrer App:

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python mit Anforderungen

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python mit SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

Sicherheitsüberlegungen

Wenn Sie eine Verbindung mit Apps aus Ihrer lokalen Umgebung herstellen, befolgen Sie die folgenden bewährten Sicherheitsmethoden:

• Nie hartcodieren Sie Zugriffstoken in Ihrem Quellcode. Verwenden Sie Umgebungsvariablen oder sichere Anmeldeinformationsspeicher.
• Aktualisieren Sie Token regelmäßig, um Sicherheitsrisiken zu minimieren, wenn sie kompromittiert werden.
• Vermeiden Sie die Protokollierung von Zugriffstoken oder vertraulichen Daten in Ihren Anwendungsprotokollen.

Problembehandlung

Wenn beim Herstellen einer Verbindung mit Ihrer App auf einem lokalen Computer Probleme auftreten, probieren Sie diese Lösungen aus.

Authentifizierungsfehler (401 Fehler)

Überprüfen Sie Folgendes:

• Ihr Token ist gültig (Ausführen databricks auth token --profile my-env)
• Ihr Profil ist ordnungsgemäß konfiguriert mit databricks auth login
• Das Token ist nicht abgelaufen.
• Ihr Token enthält die erforderlichen OAuth-Bereiche. Die Bereiche Ihres Tokens müssen eine Obermenge der Bereiche sein, die für die App in der Benutzerautorisierung konfiguriert sind.

Berechtigung verweigert (403 Fehler)

Überprüfen Sie Folgendes:

• Sie verfügen CAN USE über die Berechtigung für die App.
• Ihr Token enthält die erforderlichen OAuth-Bereiche. Unzureichende Scopes können auch dann 403-Fehler verursachen, wenn gültige Berechtigungen vorliegen.

App nicht gefunden (404 Fehler)

Überprüfen Sie Folgendes:

• Die ID- und Arbeitsbereichs-URL sind korrekt.
• Die App wird bereitgestellt und ausgeführt.
• Der Endpunktpfad ist in der App vorhanden.

Probleme mit der Netzwerkkonnektivität

Überprüfen Sie Folgendes:

• Ihr Netzwerk ermöglicht ausgehende HTTPS-Verbindungen
• Auf die *.databricksapps.com Domäne kann über Ihr Netzwerk zugegriffen werden.

Überprüfen Sie außerdem, ob Ihre Organisation einen Proxy verwendet, der eine Konfiguration erfordert.

Weitere Ressourcen

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Handbuch: Verbindung vom lokalen Computer herstellen
• Anleitung: Verbinden von externen Anwendungen
• Cookbook: Verbinden von anderen Apps
• Konfigurieren von Berechtigungen für eine Databricks-App
• Einrichten ihres Databricks-Apps-Arbeitsbereichs und ihrer Entwicklungsumgebung
• Authentifizierung für databricks CLI
• Einheitliche Databricks-Authentifizierung