Secrets-Management in Databricks: Best Practices und Patterns

TL;DR: Nutze Databricks Secret Scopes oder Azure-Key-Vault-backed Scopes — niemals Credentials im Code. dbutils.secrets.get(scope, key) liefert den Wert, ohne ihn je zu loggen. AKV-backed Scopes für Produktion (native Rotation, Azure-weiter Zugriff), Databricks-managed für Dev.

Frag irgendeinen Data Engineer nach dem größten Security-Reue, und die Antwort ist fast immer dieselbe: Credentials in einem Notebook hardgecoded, in Git committed, nie rotiert. Passiert überall, ist komplett vermeidbar.

Databricks bietet ein Secrets-Management-System, das Credentials aus deinem Code raushält. Dieser Guide deckt alles ab — von Basis-Secret-Scopes bis zu Azure-Key-Vault-Integration und Access-Control-Patterns.

Warum du eine Secrets-Strategie brauchst

Die häufigsten Credential-Exposures in Data-Plattformen passieren weil:

1. Notebook-basierte Entwicklung — es ist einfach, spark.conf.set("fs.azure.account.key...", "ACTUAL_KEY") in einer Cell zu schreiben
2. Keine Code-Reviews für Notebooks — Diff-Sichtbarkeit ist schlecht, Reviewer übersehen Hardcoded-Werte
3. Geteilte Workspaces — das Notebook eines Teams leakt versehentlich Credentials, die ein anderes Team sieht
4. Logging — Stack-Traces und Print-Statements fangen unfreiwillig Credentials ein

Databricks Secret Scopes lösen das alles — sie geben dir einen zentralisierten, ACL-kontrollierten Credential-Store, in dem Secret-Werte nie angezeigt werden, selbst nicht für Workspace-Admins.

Secret Scopes verstehen

Ein Secret Scope ist eine benannte Sammlung von Key-Value-Paaren. Zwei Typen:

• Databricks-managed Scopes — Secrets im verschlüsselten Databricks-Backend
• Azure-Key-Vault-backed Scopes — Databricks fungiert als Proxy zu einem Azure Key Vault; Secrets werden im Key Vault gespeichert und verwaltet

Welcher Typ wann?

Empfehlung: AKV-backed Scopes für Produktion. Databricks-managed für lokale Entwicklung oder wenn AKV nicht verfügbar ist.

Databricks-managed Scopes aufsetzen

Scope erstellen

# Using Databricks CLI
databricks secrets create-scope \
  --scope harbinger \
  --initial-manage-principal users

# Verify
databricks secrets list-scopes

Secrets hinzufügen

# Add a secret
databricks secrets put-secret harbinger db_password --string-value "your-password-here"

# From a file (useful for certificates, private keys)
databricks secrets put-secret harbinger ssl_cert --bytes-value @/path/to/cert.pem

# List secrets in a scope (shows keys, NOT values)
databricks secrets list-secrets harbinger

Zugriff in Notebooks und Code

# In a Databricks notebook or job
# Access a secret — value is NEVER printed/logged, even if you try
password = dbutils.secrets.get(scope="harbinger", key="db_password")

# Use it directly in connection strings
jdbc_url = "jdbc:postgresql://mydb.postgres.database.azure.com:5432/harbinger"

df = (
    spark.read
        .format("jdbc")
        .option("url", jdbc_url)
        .option("dbtable", "events")
        .option("user", dbutils.secrets.get(scope="harbinger", key="db_user"))
        .option("password", dbutils.secrets.get(scope="harbinger", key="db_password"))
        .load()
)

Wichtig: Wenn du print(password) versuchst, zeigt Databricks [REDACTED]. Der Wert lässt sich aus dem Secure-Context nicht extrahieren.

Azure-Key-Vault-backed Scopes (empfohlen für Produktion)

Voraussetzungen

1. Eine Azure-Key-Vault-Instanz
2. Ein Databricks-Service-Principal mit Key Vault Secrets User-Rolle
3. Der AKV-DNS-Name und Resource-ID

Scope via REST API erstellen

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  https://<workspace-url>/api/2.0/secrets/scopes/create \
  -d '{
    "scope": "harbinger-kv",
    "scope_backend_type": "AZURE_KEYVAULT",
    "backend_azure_keyvault": {
      "resource_id": "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>",
      "dns_name": "https://<vault-name>.vault.azure.net/"
    },
    "initial_manage_principal": "users"
  }'

Secrets im Key Vault verwalten

# Add secrets in AKV (they automatically appear in Databricks)
az keyvault secret set \
  --vault-name harbinger-kv \
  --name "cosmos-db-key" \
  --value "your-cosmos-key-here"

# Set expiration for automatic rotation awareness
az keyvault secret set \
  --vault-name harbinger-kv \
  --name "api-key-gdelt" \
  --value "your-api-key" \
  --expires "2025-01-01T00:00:00Z"

AKV-backed Secrets nutzen

Das Zugriffs-Pattern ist von Databricks-Seite identisch:

# Same API, Databricks transparently fetches from AKV
api_key = dbutils.secrets.get(scope="harbinger-kv", key="api-key-gdelt")
cosmos_key = dbutils.secrets.get(scope="harbinger-kv", key="cosmos-db-key")

Access Control (ACLs)

Secret Scopes unterstützen drei Permission-Levels: READ, WRITE und MANAGE.

# Grant read-only access to a group
databricks secrets put-acl harbinger \
  --principal data-engineers \
  --permission READ

# Grant write access to a service principal (for CI/CD)
databricks secrets put-acl harbinger \
  --principal "harbinger-cicd-sp" \
  --permission WRITE

# Grant manage access to admins
databricks secrets put-acl harbinger \
  --principal admins \
  --permission MANAGE

# View current ACLs
databricks secrets list-acls harbinger

Principle of Least Privilege

Scopes nach Access-Pattern strukturieren:

harbinger-shared/     READ für alle Data-Engineers
  - storage-account-key
  - shared-api-keys

harbinger-prod/       READ nur für prod-jobs-sp
  - prod-db-password
  - prod-api-keys

harbinger-dev/        READ+WRITE für Data-Engineers
  - dev-db-password
  - dev-api-keys

Secrets in Databricks-Workflows nutzen

In Job-Clustern via Spark-Config

Statt Secrets im Code anzurufen, kannst du sie beim Cluster-Start als Spark-Config injizieren:

{
  "spark_conf": {
    "fs.azure.account.key.harbingerprod.dfs.core.windows.net": "{{secrets/harbinger/storage-account-key}}",
    "spark.databricks.delta.preview.enabled": "true"
  }
}

Mit diesem Pattern ruft dein Anwendungscode nie dbutils.secrets — Credentials werden auf Infrastruktur-Ebene injiziert.

In Python-Packages (Non-Notebook-Code)

Wenn Python-Code als Wheel läuft (nicht als Notebook), ist dbutils nicht automatisch verfügbar. Explizit importieren:

from pyspark.dbutils import DBUtils
from pyspark.sql import SparkSession

def get_secret(scope: str, key: str) -> str:
    spark = SparkSession.getActiveSession()
    dbutils = DBUtils(spark)
    return dbutils.secrets.get(scope=scope, key=key)

Häufige Anti-Patterns

Niemals Credentials hardcoden

# NEVER DO THIS
storage_key = "2XaAbcd1234abcdefghijklmnoqrstuvwxyz=="
spark.conf.set("fs.azure.account.key.mystorage.dfs.core.windows.net", storage_key)

Niemals Widgets für Credentials nutzen

Widget-Werte sind in der Notebook-UI-History und Run-Parametern sichtbar. Nie Credentials in Widgets.

Das richtige Pattern

def build_jdbc_options(scope: str) -> dict:
    return {
        "url": "jdbc:postgresql://host:5432/db",
        "user": dbutils.secrets.get(scope, "db-user"),
        "password": dbutils.secrets.get(scope, "db-password"),
        "driver": "org.postgresql.Driver"
    }

jdbc_opts = build_jdbc_options("harbinger-prod")
df = spark.read.format("jdbc").options(**jdbc_opts).option("dbtable", "events").load()

Rotation und Auditing

Secret-Rotation

Für Databricks-managed Scopes ist Rotation manuell:

databricks secrets put-secret harbinger db_password --string-value "new-password-after-rotation"

Für AKV-backed Scopes AKV-Rotation-Policies via Azure-CLI aufsetzen:

az keyvault key rotation-policy update \
  --vault-name harbinger-kv \
  --name api-key-external \
  --value @rotation-policy.json

Audit-Logging

Jeder Secret-Zugriff wird in Databricks-Audit-Logs geloggt. Via System-Tables abfragbar:

SELECT
  timestamp,
  user_identity.email AS user,
  request_params.scopeName AS scope,
  request_params.key AS secret_key,
  response.status_code
FROM system.access.audit
WHERE action_name = 'getSecret'
  AND timestamp >= CURRENT_TIMESTAMP - INTERVAL 7 DAYS
ORDER BY timestamp DESC;

Secrets in Databricks Asset Bundles

Wenn du DABs für CI/CD nutzt, referenzierst du Secrets im Bundle-Config ohne Werte freizulegen:

resources:
  jobs:
    my_job:
      tasks:
        - task_key: main
          new_cluster:
            spark_conf:
              fs.azure.account.key.${var.storage_account}.dfs.core.windows.net: "{{secrets/${var.scope}/storage-key}}"

Die {{secrets/scope/key}}-Interpolation wird zur Laufzeit von Databricks aufgelöst, nie im YAML gespeichert.

FAQ

Sind Databricks-managed Scopes DSGVO-konform?

Ja — Daten verschlüsselt im Databricks-Backend, Audit-Logs sichtbar in System-Tables. Für strikte DSGVO-Setups in DACH: AKV-backed mit AKV in EU-Region, Rotation- und Lifecycle-Policies klar dokumentiert.

Wie rotiere ich Datenbank-Passwörter ohne Downtime?

Zwei-Stufen-Rotation: (1) Neues Passwort in AKV/Databricks-Scope schreiben unter neuem Key, (2) Jobs auf neuen Key umstellen, (3) altes Passwort aus DB entfernen. AKV-Versionierung erleichtert das.

Kann ich Secrets zwischen Workspaces teilen?

Nicht direkt. Workaround: AKV-backed Scope, der von beiden Workspaces gleichermaßen referenziert wird — das AKV ist die Source of Truth.

Was passiert, wenn ich print() auf ein Secret mache?

Databricks fängt das ab und zeigt [REDACTED]. Der Wert lässt sich aus Notebook-Output nicht extrahieren. Aber: Secrets in Files schreiben oder über API in externe Logs schicken — das schützt Databricks nicht. Daher: nie ein Secret in Variable -> Outputs senden.

Brauche ich Service-Principals für Production-Jobs?

Ja. Persönliche Tokens für produktive Jobs sind ein klassisches Anti-Pattern. Service-Principal mit minimalen Permissions + ACLs auf relevante Scopes ist der saubere Weg.

Wrap-up

Gutes Secrets-Management ist für produktive Databricks-Workspaces nicht verhandelbar. Die Kombination aus AKV-backed Scopes, Scope-Level-ACLs und dbutils.secrets gibt dir ein sicheres, auditbares, Rotation-freundliches Credential-Management.

Das Investment ist überschaubar — eine Stunde für sauberes Setup — und der Payoff ist: nie eine panische "rotate all credentials"-Nachricht um 2 Uhr morgens schreiben.

Bei Harbinger Explorer lebt jeder externe API-Key, jedes DB-Passwort und jedes Service-Token im Azure Key Vault, abgerufen via Databricks-Secret-Scopes. Null Credentials im Code, null Überraschungen in Produktion.

Stand: 14. Mai 2026.