Geheimnisse im Unity-Katalog

Auf dieser Seite wird beschrieben, wie Secrets in Unity Catalog erstellt, gelesen, gesteuert und verwaltet werden. Ein Unity-Katalogschlüssel ist ein sicherungsfähiges Objekt, das vertrauliches Material speichert, z. B. ein Kennwort, ein Token oder einen API-Schlüssel. Ihre Notebooks und Jobs können auf das Geheimnis verweisen, ohne den Wert im Code offenzulegen.

Unity Catalog Secrets verwenden den Namespace auf drei Ebenen (catalog.schema.secret) und sind in allen Arbeitsbereichen verfügbar, die an einen Metastore angebunden sind. Sie werden durch Unity-Katalogberechtigungen geregelt. Auf diese Weise können Sie dasselbe Zugriffsmodell und die gleiche Überwachung anwenden, die Sie für andere Datenressourcen auf Ihre geheimen Daten verwenden.

Note

Geheimnisse des Unity Catalog unterscheiden sich von geheimen Schlüsseln auf Arbeitsbereichsebene Azure Databricks, die in geheimen Bereichen organisiert sind. Verwenden Sie Unity Catalog-Secrets, wenn Sie Secrets mit den Unity Catalog-Berechtigungen verwalten und über den dreistufigen Namespace darauf verweisen möchten.

Funktionsweise von Geheimnissen im Unity-Katalog

Ein Unity-Kataloggeheimnis ist ein sicherungsfähiges Objekt unter einem Schema mit dem vollqualifizierten Namen catalog.schema.secret. Wie bei anderen sicherungsfähigen Objekten des Unity Catalog unterstützen geheime Schlüssel die Vererbung von Berechtigungen aus dem Katalog und Schema. Weitere Informationen zu sicherungsfähigen Objekten und Vererbung finden Sie unter Unity Catalog-Referenz zu sicherungsfähigen Objekten.

Sie können einen Unity-Katalogschlüssel auf folgende Weise verwenden:

  • Rufen Sie den Wert im Code ab. Mit READ SECRET-Zugriff können Benutzende einen geheimen Wert in Notebooks und Jobs mit dbutils oder der Unity Catalog-REST-API abrufen. Sie können sie dann zum Authentifizieren mit externen Systemen oder zum Verschlüsseln und Entschlüsseln von Daten verwenden.
  • Verwenden Sie den Wert in einem sitzungsbezogenen Python- oder Scala UDF. Siehe Session-scoped UDFs.
  • Verwenden Sie den Wert in einem Unity Catalog Python UDF. Eine skalare oder Batch-UDF deklariert jedes Geheimnis in ihrer SECRETS-Klausel. Siehe Python UDFs.
  • Verwenden Sie den Wert in einem Unity Catalog Scala UDF. Ein skalares UDF deklariert jedes Geheimnis in seiner SECRETS Klausel. Siehe Scala UDFs.

Für Anforderungen und Berechtigungsverhalten über UDF-Typen hinweg siehe UDF-Anforderungen und Berechtigungen.

UDFs können von Azure Databricks verwaltete Geheimnisse oder von einem externen Geheimnis-Manager unterstützte Geheimnisse verwenden. Siehe Externe Geheimnisse im Unity-Katalog.

UDF-Anforderungen und Berechtigungen

Anforderungen und Berechtigungsverhalten unterscheiden sich zwischen session-scoped und Unity Catalog UDFs.

Sitzungsgebundene UDFs

Eine sitzungsbezogene Python-UDF ruft mit databricks.secrets.get() ein Secret ab, und eine sitzungsbezogene Scala-UDF ruft mit com.databricks.Secrets.get() ein Secret ab. Geheimer Zugriff nutzt die Berechtigungen des Anrufers.

Die Rechenanforderungen für geheimen Zugriff hängen von der UDF-Sprache ab:

  • Bei serverloser Ausführung muss das Notebook oder die Job-Sitzung für Python- und Scala-UDFs die Umgebungsversion 6 oder höher verwenden.
  • Bei klassischem Compute sind sitzungsbezogene Python-UDFs mit Databricks Runtime 19 oder höher im Standard- oder dedizierten Zugriffsmodus erforderlich.
  • Bei klassischem Compute benötigen sitzungsbezogene Scala-UDFs Databricks Runtime 19 oder höherer Version mit dem Standardzugriffsmodus.

Unity-Katalog-UDFs

Skalare und Batch-Unity-Catalog-Python-UDFs sowie skalare Unity-Catalog-Scala-UDFs deklarieren Geheimnisse in der SECRETS-Klausel und müssen 6 explizit auf environment_version oder höher festlegen. Sie unterstützen serverlose Rechenleistungen, serverlose SQL-Warehouses und klassische Rechenleistungen mit Databricks Runtime 19 oder höher im Standardzugriffsmodus.

Pro-SQL-Warehouses unterstützen skalare und Batch Unity Catalog Python UDFs, die Geheimnisse verwenden. Unity Catalog Scala UDFs, die Geheimnisse verwenden, werden in professionellen SQL-Warehouses nicht unterstützt.

Um ein UDF zu erstellen oder zu ersetzen, das ein Secret deklariert, muss der Prinzipal, der die Anweisung ausführt, über USE CATALOG für das Secret sowie über USE SCHEMA und READ SECRET für den übergeordneten Katalog und das Schema verfügen. Während der Laufzeit verwendet das UDF die Berechtigungen des aktuellen Funktionsbesitzers. Aufrufer benötigen die üblichen Funktionsrechte, einschließlich EXECUTE, benötigen aber keinen direkten Zugriff auf die deklarierten Geheimnisse. Wenn der Funktionsbesitzer die Erlaubnis verliert, ein deklariertes Geheimnis zu lesen, scheitert das UDF.

Verwenden Sie geheimnisfähige UDFs in Spaltenmasken auf dedizierter Berechnung

Sie können eine Unity Catalog-UDF in Python oder Scala, die die SECRETS-Klausel verwendet, nicht direkt auf einer Compute-Ressource im dedizierten Zugriffsmodus aufrufen. Man kann jedoch eine Unity Catalog SQL-Funktion erstellen, die das geheimnisfähige UDF aufruft, und die SQL-Funktion als attributbasierte Zugriffskontrolle (ABAC) Spaltenmaske verwenden. Wenn eine Abfrage auf dediziertem Compute ausgeführt wird, delegiert Azure Databricks die Spaltenmaskendurchsetzung an serverlose Rechenleistungen. Diese Ausnahme gilt nur bei der Durchsetzung der Spaltenmaske; sie ermöglicht keinen direkten Aufruf der UDF mit Secret-Unterstützung auf dedizierten Compute-Ressourcen. Siehe Nicht unterstützte Compute-Versionen.

Warning

Verwenden Sie geheime Werte nur innerhalb der UDF-Implementierung. Geben Sie keine geheimen Werte zurück und fügen sie nicht in die UDF-Ergebnisse ein. Geheime Schwärzung hilft, versehentliche Sichtbarkeit in Fehlern und Protokollen zu verringern, verhindert aber nicht, dass UDF-Code geheimes Material in den Abfrageergebnissen offenlegt.

Azure Databricks speichert geheime Werte des Unity-Katalogs verschlüsselt und wendet geheime Redaction an, um die versehentliche Exposition in Ausgaben und Protokollen zu reduzieren. Um ein Secret zu rotieren, aktualisieren Sie dessen Wert regelmäßig in der Benutzeroberfläche oder mit der Unity Catalog-REST-API.

Berechtigungen für geheime Schlüssel im Unity Catalog

Die folgenden Berechtigungen gelten für Geheimnisse. Sie können sie auf Katalog-, Schema‑ oder einzelner geheimer Ebene gewähren, und sie folgen der Vererbung von Unity Catalog-Berechtigungen.

Privileg Beschreibung
CREATE SECRET Ermöglicht es einem Benutzer, einen geheimen Schlüssel in einem Schema zu erstellen. Auf Katalog- oder Schemaebene gewährt.
READ SECRET Ermöglicht es einem Benutzer, einen geheimen Wert abzurufen.
WRITE SECRET Ermöglicht es einem Benutzer, einen geheimen Wert zu aktualisieren.
REFERENCE SECRET Ermöglicht es einem Benutzer, ein Geheimnis zu referenzieren, ohne Zugriff auf den Wert zu haben.

Um ein Geheimnis in einem Schema zu erstellen, muss ein Benutzer über die Berechtigung USE CATALOG verfügen und entweder Eigentümer des Schemas sein oder über CREATE SECRET und USE SCHEMA für das Schema verfügen. Informationen zum Erteilen von Berechtigungen finden Sie unter Verwalten von Berechtigungen im Unity-Katalog.

Requirements

Um geheime Unity-Katalogschlüssel zu verwenden, müssen Sie die folgenden Anforderungen erfüllen:

  • Der Arbeitsbereich muss für Unity Catalog aktiviert sein. Eine Einführung finden Sie unter "Was ist Unity-Katalog?"
  • Sie müssen auf geheime Schlüssel von Unity Catalog-fähigen Compute zugreifen. Azure Databricks empfiehlt eine der folgenden Optionen:
  • Um geheime Schlüssel mit dbutils abzurufen, muss die Berechnung Databricks Runtime 17.3 LTS oder höher oder serverlose Umgebung, Version 4 oder höher, ausführen.

Erstellen eines Geheimnisses

Das Erstellen eines Geheimnisses erfordert, dass Sie über die Berechtigung USE CATALOG verfügen und das Schema besitzen oder für das Schema über CREATE SECRET und USE SCHEMA verfügen. Weitere Informationen finden Sie unter "Berechtigungen für Geheime Schlüssel im Unity-Katalog".

Katalog-Explorer

  1. Klicken Sie in Ihrem Azure Databricks Arbeitsbereich auf "Katalog", um den Katalog-Explorer zu öffnen.
  2. Wechseln Sie zum Schema, in dem Sie den geheimen Schlüssel erstellen möchten.
  3. Klicken Sie auf "Geheimen Schlüssel erstellen>".
  4. Geben Sie einen Namen und einen Wert ein. Fügen Sie optional einen Kommentar und ein Ablaufdatum hinzu. Wenn ein geheimer Schlüssel abläuft, zeigt der Katalog-Explorer eine Warnung an.
  5. Klicke auf Erstellen.

REST API

Führen Sie den folgenden cURL-Befehl mit dem /api/2.1/unity-catalog/secrets Endpunkt aus:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Lesen eines Geheimnisses

Um den Wert eines Geheimnisses zu lesen, müssen Sie über READ SECRET für das Geheimnis oder für einen übergeordneten Katalog bzw. ein übergeordnetes Schema verfügen.

Geheimnishilfsprogramm (dbutils.secrets)

Azure Databricks empfiehlt dbutils zum Lesen von Geheimnissen, da dabei die Schwärzung von Geheimnissen angewendet wird. Diese Option erfordert Databricks Runtime 17.3 LTS oder höher oder serverlose Umgebung, Version 4 oder höher.

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

Weitere Informationen finden Sie im Dienstprogramm "Secrets" (dbutils.secrets).

REST API

Warning

Geheime Werte, die mit der Unity Catalog REST-API abgerufen werden, unterliegen nicht der geheimen Redaction, obwohl der Zugriff weiterhin in Überwachungsprotokollen aufgezeichnet wird. Azure Databricks empfiehlt dbutils stattdessen.

Um den Wert zurückzugeben, setzen Sie include_value=true und lesen Sie das Feld effective_value in der Antwort:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Benutze ein Geheimnis in deinem Code

Nachdem Sie ein Unity-Kataloggeheimnis mit dbutils.secrets.getgelesen haben, geben Sie den zurückgegebenen Wert an Ihren Anwendungscode weiter. dbutils maskiert den Wert in Zellenausgaben und Protokollen, sodass du ihn verwenden kannst, ohne den Wert offenzulegen.

Das folgende Beispiel verwendet ein Geheimnis als Trägertoken, um eine externe API aufzurufen:

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

Das folgende Beispiel ruft einen geheimen Wert ab und übergibt ihn an dbutils.credentials.getServiceCredentialsProvider, um eine Boto3-Sitzung für das AWS SDK zu konfigurieren. Ein Service-Credential-Name ist selbst nicht sensitiv, daher speichert dieses Beispiel einen in einem Secret nur, um zu veranschaulichen, wie ein abgerufener Geheimniswert in einen anderen SDK-Aufruf verkettet wird. Weitere Informationen zu Service-Zugangsdaten finden Sie unter Use Unity Catalog Service Credentials, um sich mit externen Cloud-Diensten zu verbinden.

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

Berechtigungen für Geheimnisse verwalten

Gewähren Sie CREATE SECRET auf Katalog- oder Schemaebene, um zu steuern, wer geheime Schlüssel erstellen kann. Gewähren Sie READ SECRET, WRITE SECRET oder REFERENCE SECRET auf Katalog-, Schema‑ oder einzelner Geheimnisebene, um den Zugriff zu steuern. Berechtigungsvererbung gilt. Weitere Informationen zum Gewähren und Widerrufen von Berechtigungen finden Sie unter Verwalten von Berechtigungen im Unity-Katalog.

Berechtigung zum Erstellen von Geheimnissen gewähren

Katalog-Explorer

  1. Wechseln Sie im Katalog-Explorer zum Schema.

  2. Klicken Sie auf die Registerkarte Berechtigungen.

  3. Klicken Sie auf Erlauben.

  4. Wählen Sie die Prinzipale aus, denen Zugriff gewährt werden soll, und wählen Sie dann die Option CREATE SECRET aus.

    Wenn ein Sicherheitsprinzipal nicht über USE SCHEMA verfügt, werden Sie durch eine Warnung aufgefordert, es zu gewähren. USE SCHEMA ist auch erforderlich, um geheime Schlüssel im Schema zu erstellen.

  5. Klicken Sie auf Bestätigen.

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

Führen Sie den folgenden cURL-Befehl mit dem /api/2.1/unity-catalog/permissions/schema/{schema_name} Endpunkt aus:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

Zugriff auf ein Geheimnis gewähren

Katalog-Explorer

  1. Wechseln Sie im Catalog Explorer zum Secret, und klicken Sie darauf.
  2. Klicken Sie auf die Registerkarte Berechtigungen.
  3. Klicken Sie auf Erlauben.
  4. Wählen Sie die Prinzipale und die zu gewährenden Berechtigungen aus, und klicken Sie dann auf "Bestätigen".

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

Führen Sie den folgenden cURL-Befehl mit dem /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} Endpunkt aus:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

Auflisten, Aktualisieren und Löschen geheimer Schlüssel

Geheimnisse auflisten

Katalog-Explorer

  1. Wechseln Sie im Katalog-Explorer zum Schema.
  2. Klicken Sie im Bereich "Übersicht " auf "Geheime Schlüssel ", um alle geheimen Schlüssel im Schema anzuzeigen.

Geheimnishilfsprogramm (dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

Nutze page_size es, um die Anzahl der Ergebnisse pro Seite zu kontrollieren. Wenn weitere Ergebnisse vorliegen, enthält die Antwort :next_page_token

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_size=100" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Um die nächste Seite abzurufen, geben Sie den next_page_token Wert der vorherigen Antwort als Parameter page_token weiter:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_token=<next_page_token>" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Geheimnis aktualisieren

Um einen Secret-Wert zu aktualisieren, müssen Sie für das Secret über WRITE SECRET verfügen.

Katalog-Explorer

  1. Wechseln Sie im Katalog-Explorer zum Schema, und klicken Sie im Bereich "Übersicht" auf "Geheime Schlüssel".
  2. Klicken Sie auf den geheimen Schlüssel, um es zu aktualisieren.
  3. Klicken Sie in der oberen rechten Ecke auf das Kebab-Menü (vertikale Punkte), und wählen Sie "Bearbeiten" aus.
  4. Geben Sie einen neuen Wert oder ein Ablaufdatum ein, und klicken Sie dann auf "Bestätigen".

REST API

Aktualisierungsanforderungen erfordern den update_mask Parameter. Es werden nur Felder aktualisiert, die sowohl in update_mask als auch im Request-Body enthalten sind:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

Löschen eines Geheimnisses

Katalog-Explorer

  1. Wechseln Sie im Katalog-Explorer zum Schema, und klicken Sie im Bereich "Übersicht" auf "Geheime Schlüssel".
  2. Klicken Sie auf den geheimen Schlüssel, um es zu löschen.
  3. Klicken Sie in der oberen rechten Ecke auf das Kebab-Menü (vertikale Punkte), und wählen Sie "Löschen" aus.
  4. Geben Sie den vollständigen Namen des geheimen Schlüssels ein, und klicken Sie dann auf "Löschen".

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Überwachungsereignisse für Unity Catalog-Geheimnisse

Die Systemtabelle system.access.audit zeichnet Ereignisse im Zusammenhang mit den Geheimnissen des Unity Catalog auf. Um beispielsweise alle geheimen Ereignisse für einen Benutzer an einem bestimmten Datum anzuzeigen, führen Sie die folgende Abfrage aus:

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

Weitere Informationen zu Überwachungsprotokollen finden Sie in der Referenz zur Systemtabelle des Überwachungsprotokolls.

Verschlüsseln geheimer Werte mit vom Kunden verwalteten Schlüsseln

Standardmäßig verschlüsselt Azure Databricks geheime Werte mit von Databricks verwalteten Schlüsseln. Sie können stattdessen vom Kunden verwaltete Schlüssel (CMK) verwenden. Wenn Sie das MIT CMK verschlüsselte Feature für verwalteten Katalog aktivieren und eine CMK-Konfiguration an Ihr Konto anfügen, verwendet Azure Databricks die CMK zum Verschlüsseln geheimer Werte. Weitere Informationen finden Sie unter vom Kunden verwaltete Schlüssel für den Unity-Katalog.

Secrets mit einem externen Secret-Manager sichern

Anstatt dass Azure Databricks geheime Werte speichert, können Sie ein Schema mit einem externen Geheimenmanager sichern, sodass die Werte im Cloud-Geheimnismanager bleiben und in Unity Catalog steuerbar bleiben. AWS Secrets Manager auf AWS und Azure Key Vault auf Azure werden unterstützt. Wie externe Geheimnisse funktionieren, siehe Externe Geheimnisse im Unity-Katalog. Um ein Schema mit einem externen Secret-Manager zu unterstützen, siehe Configure external secrets in Unity Catalog.

Einschränkungen

Die Geheimnisse des Unity-Katalogs weisen die folgenden Einschränkungen auf:

  • Begrenzter direkter Zugriff von SQL-Warehouses. Man kann Unity Catalog Secrets nicht direkt aus SQL-Warehouses abrufen. Skalare und Batch-Unity-Catalog-Python-UDFs können in Pro- und serverlosen SQL-Warehouses auf Geheimnisse zugreifen, die in ihren SECRETS-Klauseln deklariert sind. Scalar Unity Catalog Scala UDFs können auf deklarierte Geheimnisse nur auf serverlosen SQL-Warehouses zugreifen.
  • Kein direkter SECRETS UDF-Aufruf bei dedizierter Rechenleistung. Skalare oder Batch-Unity-Catalog-Python-UDFs sowie skalare Unity-Catalog-Scala-UDFs, die die Klausel SECRETS verwenden, können auf Compute mit dediziertem Zugriffsmodus nicht direkt aufgerufen werden. Für die Ausnahme bei Spaltenmasken siehe Verwenden von UDFs mit Secret-Unterstützung in Spaltenmasken auf dedizierten Compute-Ressourcen.
  • Keine globale Erkennung. Geheimnisse des Unity-Katalogs werden in der globalen Suche nicht angezeigt.
  • Keine BROWSE-Berechtigungsunterstützung. BROWSE in einem Katalog gilt nicht für Unity Catalog-Geheimnisse. Um ein Geheimnis auffindbar zu machen, gewähren Sie READ SECRET oder REFERENCE SECRET für das einzelne Geheimnis oder dessen Schema.
  • Keine Initskripts. Sie können die Geheimen Schlüssel des Unity-Katalogs nicht in globalen oder Cluster-Init-Skripts verwenden. Azure Databricks empfiehlt, dedizierte Features anstelle von Init-Skripts zu verwenden, wenn möglich.
  • Kein Informationsschema. Tabellen des Informationsschemas für Geheimnisse sind noch nicht verfügbar. Verwenden Sie den Katalog-Explorer oder die REST-API für die Ermittlung.
  • dbutils Laufzeitbereich. dbutils Das Abrufen wird für Databricks Runtime-gesicherte Notebooks und Aufträge unterstützt. Nicht-Databricks-Runtime-Kontexte, z. B. Remoteentwicklungs- oder kompilierte JAR-Ausführungsmodi, werden nicht unterstützt.
  • OAuth-API-Bereich. Auf die Geheim-API des Unity-Katalogs kann nur über den unity-catalog OAuth-API-Bereich zugegriffen werden. Verwenden Sie den secrets API-Geheimbereich nur für Azure Databricks-Geheimnisse auf Arbeitsbereichsebene.
  • Kontingentbeschränkungen. Bis zu 100 geheime Schlüssel pro Schema und 1.000 pro Metastore.