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.

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-Katalogs 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 Benutzer 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.
• Verweisen Sie auf den Wert aus Objekten in Unity Catalog. Unity Catalog-Objekte, z. B. Unity Catalog-Verbindungen, können anhand des Namens auf einen geheimen Schlüssel verweisen, sodass eine Integration den geheimen Schlüssel verwenden kann, ohne Benutzern Zugriff auf den Wert zu gewähren. Je nach Objekt erfordert das Verweisen auf einen geheimen Schlüssel entweder REFERENCE SECRET oder READ SECRET.

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-Katalog

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-Katalogberechtigungen.

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.

Bevor Sie anfangen

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:
  • Serverlose Jobs und Notebooks mit Umgebungen ab Version 4.
  • Klassische Berechnung im Standardzugriffsmodus mit Databricks Runtime 17.3 LTS oder höher.
• Um geheime Schlüssel dbutilsabzurufen, 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 Secrets zu lesen, müssen Sie über READ SECRET für das Secret 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

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"

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 Secret-Ebene, 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 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

Listenabfragen verwenden page_size, um die Anzahl der Ergebnisse zu steuern:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$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 geheime Unity-Katalogschlüssel

Die system.access.audit Systemtabelle zeichnet Ereignisse im Zusammenhang mit den Geheimschlüsseln des Unity-Katalogs 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.

Einschränkungen

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

• Keine SQL-Lagerhäuser. Geheime Schlüssel des Unity-Katalogs werden in SQL-Lagerhäusern nicht unterstützt. Sie erfordern Databricks Runtime 17.3 LTS oder höher auf Unity Catalog-fähigen Compute oder serverlos.
• 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-Katalogschlüssel. 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 Notizbücher 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.