Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Ein Unity-Catalog-Geheimnis ist ein sicherbares Objekt, das sensible Zugangsdaten wie ein Passwort, ein Token oder einen API-Schlüssel speichert. Secrets verwenden den dreistufigen Namensraum (catalog.schema.secret) und sind in jedem Arbeitsbereich verfügbar, der dem Metastore angegliedert ist.
Du steuerst Secrets mit denselben Unity-Catalog-Privilegien wie deine anderen Datenressourcen, bis hin zum einzelnen Secret. Benutzer können ein Geheimnis durchsuchen, ohne es lesen oder verwenden zu können, man kann Geheimniswerte mit einem eigenen Schlüssel verschlüsseln, und Audit-Protokolle erfassen jedes Lesen und jede Änderung.
Unity Catalog-Geheimnisse können von Azure Databricks verwaltet oder durch Azure Key Vault unterstützt werden. Siehe Azure Key Vault Secrets im Unity Catalog.
Requirements
- Der Arbeitsbereich muss für Unity Catalog aktiviert sein. Siehe Was ist Unity Catalog?.
- Um Secrets mit
dbutilszu lesen, verwenden Sie serverlose Notebooks und Jobs auf Umgebungsversion 4 und höher oder klassische Compute-Ressourcen mit Databricks Runtime 17.3 LTS und höher. Azure Databricks empfiehlt den serverlosen oder den Standardzugriffsmodus. - Um Secrets in UDFs zu verwenden, siehe Use secrets in UDFs.
Erstellen eines Geheimnisses
Geheimnisse leben in Schemata. Erstellen Sie Secrets in einem Schema, auf das nur die Prinzipale, die sie benötigen, Zugriff haben. Informationen dazu, wie man Secrets in Schemata gruppiert, finden Sie unter Secrets danach gruppieren, wer sie benötigt.
Ein Schema enthält von Azure Databricks verwaltete Geheimnisse oder Azure Key Vault-gestützte Geheimnisse, nicht beides, sodass Sie beim Einrichten des Schemas wählen, wo die Werte gespeichert werden. Für ein von Azure Key Vault unterstütztes Schema siehe Erstellen eines Geheimnisses in einem von Azure Key Vault unterstützten Schema.
Ein Azure Databricks-verwaltetes Geheimnis erstellen
Um ein von Azure Databricks verwaltetes Geheimnis zu erstellen, benötigen Sie USE CATALOG im Katalog und entweder das Eigentum am Schema oder CREATE SECRET und USE SCHEMA darauf.
Um ein Schema für die Geheimnisse einer Anwendung zu erstellen, führen Sie Folgendes aus:
CREATE SCHEMA IF NOT EXISTS main.orders_app;
Katalog-Explorer
- Klicken Sie in Ihrem Azure Databricks Arbeitsbereich auf "Katalog", um den Katalog-Explorer zu öffnen.
- Wechseln Sie zum Schema, in dem Sie den geheimen Schlüssel erstellen möchten.
- Klicken Sie auf "Geheimen Schlüssel erstellen>".
- 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.
- Klicke auf Erstellen.
REST API
Um ein Secret zu erstellen, führe Folgendes aus:
curl -X POST \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"catalog_name": "main",
"schema_name": "orders_app",
"name": "db_password",
"value": "your_secret_value",
"comment": "Password for the orders database"
}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
Ein Geheimnis in einem Azure Key Vault-gestützten Schema erstellen
Ein Administrator sichert ein Schema einmal mit Azure Key Vault. Danach erstellt, aktualisiert und rotiert man die zugehörigen Geheimnisse in Azure Key Vault, und sie erscheinen im Schema in Unity Catalog. Informationen zum Sichern eines Schemas finden Sie unter Azure Key Vault-Secrets in Unity Catalog.
- Erstellen Sie das Geheimnis im Azure Key Vault, dem das Schema zugrunde liegt.
- Lesen Sie das Geheimnis anhand des Namens. Siehe Lies ein Geheimnis.
Zugriff auf Geheimnisse gewähren
Gewähren Sie das Privileg, das dem entspricht, was jeder Prinzipal tun muss. Außer mit BROWSE benötigt jeder Prinzipal auch USE CATALOG und USE SCHEMA im übergeordneten Katalog und Schema. Ein auf einem Katalog oder Schema gewährtes Privileg gilt für die darin enthaltenen Secrets, einschließlich später erstellter Secrets.
| Um einen Prinzipal zuzulassen | Grant |
|---|---|
| Lesen Sie den Wert in einem Notebook, Job oder einem REST-API-Aufruf | READ SECRET |
| Entdecken Sie bestimmte Geheimnisse, ohne ihre Werte einzusehen |
REFERENCE SECRET für das Geheimnis oder Schema, wenn BROWSE auf dem gesamten Katalog zu breit gefasst ist. Es gibt keinen Lesezugriff und lässt den Prinzipal den Wert nicht verwenden. |
| Wert aktualisieren |
WRITE SECRET. Gewährt man nur dieses Privileg, erhält man keinen Lesezugriff auf das Secret. |
| Erstelle Secrets in einem Schema |
CREATE SECRET im Schema oder Katalog |
| Anderen Berechtigungen für Secrets gewähren | Eigentum oder MANAGE auf dem Secret, Schema oder Katalog |
Um Rechte zu gewähren, verwenden Sie den Catalog Explorer: Öffnen Sie das Secret oder das Schema, klicken Sie auf den Reiter Berechtigungen und klicken Sie auf Gewähren. Um Berechtigungen per SQL zu vergeben, führen Sie Folgendes aus:
-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;
-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;
Weitere Informationen finden Sie unter Verwalten von Berechtigungen in Unity Catalog.
Lesen eines Geheimnisses
Um einen geheimen Wert zu lesen, braucht man Eigentum am Geheimnis oder READ SECRET auf dem Geheimnis oder auf seinem Schema oder Katalog.
Geheimnishilfsprogramm (dbutils.secrets)
Azure Databricks empfiehlt dbutils, da es den Wert in Zellenausgaben und Protokollen schwärzt. Das folgende Beispiel liest einen Datenbank-Benutzernamen und ein Passwort, um einen JDBC-Lesevorgang zu konfigurieren:
username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")
df = (spark.read
.format("jdbc")
.option("url", "<jdbc-url>")
.option("dbtable", "<table-name>")
.option("user", username)
.option("password", password)
.load()
)
Siehe Secrets-Utility (dbutils.secrets).
REST API
Warning
Die Unity Catalog REST API schwärzt keine zurückgegebenen Werte. Audit-Protokolle dokumentieren weiterhin jeden Lesezugriff. 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.orders_app.db_password"
Auflisten, Aktualisieren und Löschen geheimer Schlüssel
Um einen Wert zu aktualisieren, brauchen Sie WRITE SECRET für das Geheimnis. Um den Kommentar oder das Ablaufdatum zu ändern oder ihn zu löschen, benötigt man die Eigentümerschaft des Geheimnisses oder MANAGE dafür, für sein Schema oder seinen Katalog.
Für ein von Azure Key Vault unterstütztes Schema aktualisieren und löschen Sie Secrets in Azure Key Vault. Löschungen werden in Unity Catalog übernommen.
Katalog-Explorer
- In Catalog Explorer gehen Sie zum Schema und klicken im Übersicht-Bereich auf Secrets, um dessen Secrets aufzulisten.
- Klicken Sie auf das Secret, das Sie ändern möchten.
- Klicken Sie oben rechts auf das Kebabmenü (vertikale Punkte) und wählen Bearbeiten oder Löschen.
- Zum Bearbeiten geben Sie einen neuen Wert oder ein neues Ablaufdatum ein und klicken Sie auf Bestätigen. Zum Löschen geben Sie den vollständigen Namen des Secrets ein und klicken Sie auf Löschen.
Geheimnishilfsprogramm (dbutils.secrets)
Um die Geheimnisse aufzulisten, auf die Sie in einem Schema zugreifen können, führen Sie Folgendes aus:
all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")
REST API
Um Geheimnisse aufzulisten, führe Folgendes aus. Wenn weitere Ergebnisse verfügbar sind, geben Sie das next_page_token der Antwort als page_token weiter:
curl -G \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
--data-urlencode "catalog_name=main" \
--data-urlencode "schema_name=orders_app" \
--data-urlencode "page_size=100" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
Um einen Wert zu aktualisieren, führe Folgendes aus. Nur Felder in beiden update_mask und dem Request-Body ändern sich:
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.orders_app.db_password?update_mask=*"
Um ein Geheimnis zu löschen, führen Sie Folgendes aus:
curl -X DELETE \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
Geheimnisse taggen
Unity Catalog-Secrets unterstützen Schlüsselwert-Tags, zum Beispiel zur Klassifizierung von Geheimnissen oder zur Erfassung des besitzenden Teams oder der Kostenstelle. Weitere Informationen finden Sie unter Anwenden von Tags auf sicherungsfähige Unity Catalog-Objekte.
Um einem Secret Tags hinzuzufügen oder zu entfernen, müssen Sie das Secret besitzen oder über alle folgenden Berechtigungen verfügen:
-
APPLY TAGfür das Geheimnis -
USE SCHEMAauf dem übergeordneten Schema des Geheimnisses -
USE CATALOGim übergeordneten Katalog des Secrets
Um einen Governed Tag zuzuweisen, benötigen Sie außerdem die ASSIGN Berechtigung für den Governed Tag. Siehe "Verwalten von Berechtigungen für geregelte Tags".
Um einen Tag mit SQL hinzuzufügen oder zu entfernen, führen Sie Folgendes aus:
SET TAG ON SECRET main.orders_app.db_password cost_center = hr;
UNSET TAG ON SECRET main.orders_app.db_password cost_center;
Um die Tags auf einem Geheimnis anzuzeigen, verwenden Sie eine der folgenden Möglichkeiten:
Katalog-Explorer
- Wechseln Sie im Katalog-Explorer zum Schema, und klicken Sie im Bereich "Übersicht" auf "Geheime Schlüssel".
- Klicken Sie auf das Secret. Seine Tags erscheinen unter Tags auf der Registerkarte Übersicht .
REST API
Um die Tags auf einem Geheimnis aufzulisten, führen Sie Folgendes aus. Wenn weitere Ergebnisse verfügbar sind, geben Sie das next_page_token der Antwort als page_token weiter:
curl \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/entity-tag-assignments/secrets/main.orders_app.db_password/tags"
CLI
Um die Tags auf einem Geheimnis aufzulisten, führen Sie Folgendes aus:
databricks entity-tag-assignments list secrets main.orders_app.db_password
Tags von Secrets erscheinen nicht in der Ausgabe von DESCRIBE SECRET, in der Antwort der API, mit der ein Secret abgerufen wird, in Informationsschematabellen oder in der Arbeitsraumsuche.
Audit-Geheimniszugriff
Die system.access.audit Systemtabelle zeichnet geheime Ereignisse auf. Lesevorgänge erscheinen mit action_name = 'getSecret'. Um die letzten 7 Tage geheimer Ereignisse aufzulisten, führe Folgendes durch:
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
AND action_name LIKE '%Secret%'
AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;
Siehe Verweis auf die Systemtabelle des Audit-Logbuchs.
Verschlüsseln Sie geheime Werte mit kundenverwalteten Schlüsseln
Azure Databricks verschlüsselt Secret Values standardmäßig mit Azure Databricks-managed Keys. Um Ihren eigenen Schlüssel zu verwenden, konfigurieren Sie kundenverwaltete Schlüsseleinstellungen (CMK) im Katalog, der die Geheimnisse enthält. Geheimwerte werden in Unity Catalog gespeichert, nicht im Speicherort des Katalogs, daher funktioniert dies für jeden Katalog, auch für einen mit einem externen Speicherort. Für Anforderungen und Einrichtung siehe Kundenverwaltete Schlüssel für Unity Catalog.
Externe Geheimniswerte bleiben in Ihrem Cloud-Geheimnismanager, der sie mit eigenen Schlüsseln verschlüsselt. CMK-Einstellungen im Katalog gelten nicht für diese.
Geheimnisse in UDFs verwenden
Ein Unity Catalog Python- oder Scala-UDF kann einen geheimen Wert verwenden, ohne den Aufrufern Zugriff auf den geheimen Wert zu gewähren. Deklarieren Sie das Secret in der SECRETS Klausel der UDF. Der UDF liest sie mit den Berechtigungen des Funktionsbesitzers:
- Der Besitzer braucht
READ SECRETfür das Geheimnis, um das UDF zu erstellen oder zu ersetzen. Wenn der BesitzerREAD SECRETverliert, scheitert das UDF. - Anrufer brauchen nur
EXECUTEauf dem UDF und kein Privileg auf dem Geheimnis.
Die UDF-Definition muss environment_version auf 6 oder höher setzen. Im klassischen Compute-Modus verwenden Sie Databricks Runtime 19 und höher im Standardzugriffsmodus. Beispiele finden sich in Python UDFs und Scala UDFs.
Sitzungsbezogene UDFs, die databricks.secrets.get() oder com.databricks.Secrets.get() verwenden, lesen Geheimnisse mit den Berechtigungen des Anrufers, sodass jeder Anrufer READ SECRETbenötigt. Siehe Python UDFs und Scala UDFs.
Bei Dedicated Access Mode Compute können Sie diese UDFs nicht direkt aufrufen. Sie können eine davon aus einer Unity Catalog SQL-Funktion aufrufen, die Sie als ABAC-Spaltenmaske verwenden, die Azure Databricks bei serverlosem Compute erzwingt. Siehe Nicht unterstützte Compute-Versionen.
Warning
Verwenden Sie geheime Werte nur innerhalb der UDF. Geben Sie sie nicht in den UDF-Ergebnissen zurück. Redaction reduziert die versehentliche Offenlegung in Fehlermeldungen und Protokollen, verhindert aber nicht, dass UDF-Code ein Geheimnis in den Abfrageergebnissen zurückgibt.
Einschränkungen
- Quoten: Ein Schema kann bis zu 1.000 Geheimnisse speichern, ein Metaspeicher bis zu 10.000.
-
Keine globale Suche oder Informationsschema: Geheimnisse erscheinen nicht in globalen Such- oder Informationsschematabellen. Verwenden Sie den Catalog Explorer
dbutilsoder die REST-API. -
OAuth-API-Bereich: Die Unity Catalog Secrets API erfordert den
unity-catalogOAuth-API-Bereich. Der Bereichsecretsgilt nur für Workspace-Geheimnis-Scopes. - Init-Skripte: Sie können Unity Catalog-Geheimnisse nicht in globalen oder clusterbasierten Init-Skripten verwenden.
-
Remote-Entwicklung: Databricks Connect und kompilierte JAR-Laufzeitmodi können Unity Catalog-Secrets nicht lesen, da
dbutils.secretsdafür ein von Databricks Runtime unterstütztes Notebook oder ein Job erforderlich ist.
Zusätzliche Ressourcen
| Resource | Beschreibung |
|---|---|
| Best Practices für Geheimnisse in Unity Catalog | Organisieren Sie Geheimnisse nach Umgebung, Anwendung oder Team und lassen Sie Workloads Geheimnisse verwenden, ohne sie zu lesen. |
| Verwaltung von Geheimnissen | Vergleichen Sie Unity Catalog-Geheimnisse mit Workspace-Geheimnisbereichen, und erfahren Sie, wo Sie diese jeweils verwenden können. |