Geheimen in Unity Catalog

Important

Deze functie bevindt zich in openbare preview-versie.

Deze pagina beschrijft hoe u geheimen in Unity Catalog maakt, leest, governance toepast op en beheert. Een Unity Catalog-geheim is een beveiligbaar object waarin gevoelig materiaal wordt opgeslagen, zoals een wachtwoord, token of API-sleutel. Uw notebooks en taken kunnen verwijzen naar het geheim zonder de waarde in code weer te geven.

Unity Catalog-geheimen maken gebruik van de naamruimte op drie niveaus (catalog.schema.secret) en zijn beschikbaar in de werkruimten die zijn gekoppeld aan een metastore. Unity Catalog-privileges zijn erop van toepassing. Hiermee kunt u hetzelfde toegangsmodel en dezelfde controle toepassen die u gebruikt voor andere gegevensassets voor uw geheimen.

Note

Unity Catalog-geheimen verschillen van Azure Databricks-secrets op workspace-niveau, die zijn georganiseerd in secret scopes. Gebruik Unity Catalog-geheimen als u geheimen met Unity Catalog-bevoegdheden wilt beheren en ernaar wilt verwijzen met de naamruimte op drie niveaus.

Hoe Unity Catalog-geheimen werken

Een Unity Catalog-geheim is een beveiligbaar object onder een schema, met de volledig gekwalificeerde naam catalog.schema.secret. Net als andere beveiligbare objecten van Unity Catalog bieden geheimen ondersteuning voor overname van bevoegdheden vanuit de catalogus en het schema. Zie de naslaginformatie over beveiligbare objecten in Unity Catalog voor meer informatie over beveiligbare objecten en overname.

U kunt op de volgende manieren een Unity Catalog-geheim gebruiken:

  • Haal de waarde in code op. Met READ SECRET-toegang kunnen gebruikers een geheime waarde opvragen vanuit notebooks en jobs met behulp van dbutils of de Unity Catalog REST API. Ze kunnen deze vervolgens gebruiken voor verificatie met externe systemen of voor het versleutelen en ontsleutelen van gegevens.
  • Verwijs naar de waarde van Unity Catalog-objecten. Unity Catalog-objecten, zoals Unity Catalog-verbindingen, kunnen verwijzen naar een geheim op naam, zodat een integratie het geheim kan gebruiken zonder gebruikers toegang te geven tot de waarde. Afhankelijk van het object vereist het verwijzen naar een geheim REFERENCE SECRET of READ SECRET.

Azure Databricks slaat geheime waarden van Unity Catalog versleuteld op en past geheime bewerkingen toe om onbedoelde blootstelling in uitvoer en logboeken te verminderen. Als u een geheim wilt roteren, werkt u de waarde ervan periodiek bij in de UI of via de Unity Catalog REST API.

Bevoegdheden voor Unity Catalog-geheimen

De volgende bevoegdheden zijn van toepassing op geheimen. U kunt deze toekennen op catalogus-, schema- of individueel geheimniveau, en ze volgen de overerving van machtigingen in Unity Catalog.

Voorrecht Omschrijving
CREATE SECRET Hiermee kan een gebruiker een geheim maken in een schema. Verleend op catalogus- of schemaniveau.
READ SECRET Hiermee kan een gebruiker een geheime waarde ophalen.
WRITE SECRET Hiermee kan een gebruiker een geheime waarde bijwerken.
REFERENCE SECRET Hiermee kan een gebruiker verwijzen naar een geheim, bijvoorbeeld vanuit een Unity Catalog-verbinding, zonder toegang tot de waarde.

Om een geheim in een schema aan te maken, moet een gebruiker beschikken over de toestemming USE CATALOG en ofwel de eigenaar zijn van het schema, of beschikken over CREATE SECRET en USE SCHEMA voor het schema. Zie Bevoegdheden beheren in Unity Catalog voor meer informatie over het verlenen van bevoegdheden.

Voordat u begint

Als u Unity Catalog-geheimen wilt gebruiken, moet u voldoen aan de volgende vereisten:

  • De werkruimte moet zijn ingeschakeld voor Unity Catalog. Zie Wat is Unity Catalog? voor een inleiding.
  • U moet toegang krijgen tot geheimen vanuit compute met Unity Catalog. Azure Databricks raadt een van de volgende opties aan:
  • Om geheimen op te halen met dbutils, moet de compute Databricks Runtime 17.3 LTS of hoger uitvoeren, of serverless-omgeving versie 4 of hoger.

Een geheim maken

Voor het maken van een geheim moet u beschikken over de machtiging USE CATALOG en eigenaar zijn van het schema, of beschikken over CREATE SECRET en USE SCHEMA voor het schema. Zie Bevoegdheden voor Unity Catalog-geheimen.

Catalogusverkenner

  1. Klik in uw Azure Databricks werkruimte op Catalogus om Catalog Explorer te openen.
  2. Ga naar het schema waar u het geheim wilt maken.
  3. Klik op Geheim maken>.
  4. Voer een naam en waarde in. Voeg eventueel een opmerking en een vervaldatum toe. Als een geheim verloopt, wordt in Catalog Explorer een waarschuwing weergegeven.
  5. Klik op Create.

REST API

Voer de volgende cURL-opdracht uit met behulp van het /api/2.1/unity-catalog/secrets eindpunt:

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"

Lees een geheim

Als u een geheime waarde wilt lezen, moet u beschikken over READ SECRET voor het geheim of voor een bovenliggende catalogus of een bovenliggend schema.

Secrets-hulpprogramma (dbutils.secrets)

Azure Databricks raadt dbutils aan om geheimen te lezen, omdat het geheime redaction toepast. Voor deze optie is Databricks Runtime 17.3 LTS of hoger of serverloze omgevingsversie 4 of hoger vereist.

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

Zie het hulpprogramma Geheimen (dbutils.secrets) voor meer informatie.

REST API

Warning

Geheime waarden die worden opgehaald met de Unity Catalog REST API, zijn niet onderhevig aan geheime redaction, maar de toegang wordt nog steeds vastgelegd in auditlogboeken. Azure Databricks raadt dbutils in plaats daarvan aan.

Als u de waarde wilt terugkrijgen, stelt u include_value=true in en leest u het veld effective_value in het antwoord:

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

Machtigingen voor geheimen beheren

Geef CREATE SECRET op catalogus- of schemaniveau aan wie geheimen kan maken. Verleen READ SECRET, WRITE SECRET of REFERENCE SECRET op catalogus-, schema- of individueel geheimniveau om toegang te beheren. Machtigingsovererving is van toepassing. Zie Bevoegdheden beheren in Unity Catalog voor meer informatie over het verlenen en intrekken van bevoegdheden.

De mogelijkheid verlenen om geheimen te maken

Catalogusverkenner

  1. Ga in Catalog Explorer naar het schema.

  2. Klik op het tabblad Machtigingen .

  3. Klik op Toestaan.

  4. Selecteer de principalen waaraan u toegang wilt verlenen en selecteer vervolgens CREATE SECRET.

    Als een beveiligingsprincipal niet over USE SCHEMA beschikt, wordt u door een waarschuwing gevraagd dit te verlenen. USE SCHEMA is ook vereist voor het maken van geheimen in het schema.

  5. Klik op Bevestigen.

SQL

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

REST API

Voer de volgende cURL-opdracht uit met behulp van het /api/2.1/unity-catalog/permissions/schema/{schema_name} eindpunt:

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}"

Toegang verlenen tot een geheim

Catalogusverkenner

  1. Ga in Catalog Explorer naar het geheim en klik erop.
  2. Klik op het tabblad Machtigingen .
  3. Klik op Toestaan.
  4. Selecteer de principals en de bevoegdheden die u wilt verlenen en klik vervolgens op Bevestigen.

SQL

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

REST API

Voer de volgende cURL-opdracht uit met behulp van het /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} eindpunt:

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}"

Geheimen weergeven, bijwerken en verwijderen

Geheimen weergeven

Catalogusverkenner

  1. Ga in Catalog Explorer naar het schema.
  2. Klik in het deelvenster Overzicht op Geheimen om alle geheimen in het schema weer te geven.

Secrets-hulpprogramma (dbutils.secrets)

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

REST API

Lijstverzoeken gebruiken page_size om het aantal resultaten te regelen:

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"

Een geheim bijwerken

Om de waarde van een geheim bij te werken, moet u WRITE SECRET op het geheim hebben.

Catalogusverkenner

  1. Ga in Catalog Explorer naar het schema en klik op Geheimen in het deelvenster Overzicht .
  2. Klik op het geheim om bij te werken.
  3. Klik in de rechterbovenhoek op het kebabmenu (verticale drie puntjes) en selecteer Bewerken.
  4. Voer een nieuwe waarde of vervaldatum in en klik op Bevestigen.

REST API

Voor updateaanvragen is de update_mask parameter vereist. Alleen velden die zijn opgenomen in zowel update_mask de aanvraagtekst als de hoofdtekst van de aanvraag, worden bijgewerkt:

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=*"

Een geheim verwijderen

Catalogusverkenner

  1. Ga in Catalog Explorer naar het schema en klik op Geheimen in het deelvenster Overzicht .
  2. Klik op het geheim dat u wilt verwijderen.
  3. Klik in de rechterbovenhoek op het kebabmenu (verticale puntjes) en kies Verwijderen.
  4. Voer de volledige naam van het geheim in en klik vervolgens op Verwijderen.

REST API

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

Controlegebeurtenissen voor Unity Catalog-geheimen

De system.access.audit systeemtabel registreert gebeurtenissen met betrekking tot Unity Catalog-geheimen. Als u bijvoorbeeld alle geheime gebeurtenissen voor een gebruiker op een specifieke datum wilt zien, voert u de volgende query uit:

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%";

Zie Systeemtabelverwijzing voor auditlogboeken voor meer informatie over auditlogboeken.

Geheime waarden versleutelen met door de klant beheerde sleutels

Standaard versleutelt Azure Databricks geheime waarden met door Databricks beheerde sleutels. U kunt in plaats daarvan door de klant beheerde sleutels (CMK) gebruiken. Als u de functie voor door CMK versleutelde beheerde catalogus inschakelt en een CMK-configuratie aan uw account koppelt, gebruikt Azure Databricks de CMK om geheime waarden te versleutelen. Zie Door de klant beheerde sleutels voor Unity Catalog voor meer informatie.

Limitations

Unity Catalog-geheimen hebben de volgende beperkingen:

  • Geen SQL-magazijnen. Unity Catalog-geheimen worden niet ondersteund in SQL-warehouses. Hiervoor is Databricks Runtime 17.3 LTS of hoger vereist op rekenresources waarvoor Unity Catalog is ingeschakeld, of op serverloze compute.
  • Geen globale detectie. Unity Catalog-geheimen worden niet weergegeven in globale zoekopdrachten.
  • Geen ondersteuning voor BROWSE-machtigingen. BROWSE op een catalogus is niet van toepassing op Unity Catalog-geheimen. Als u een geheim vindbaar wilt maken, verleent u READ SECRET of REFERENCE SECRET op het afzonderlijke geheim of het bijbehorende schema.
  • Geen initialisatiescripts. U kunt geen Unity Catalog-geheimen gebruiken in globale of cluster-init-scripts. Azure Databricks raadt u aan om waar mogelijk speciale functies te gebruiken in plaats van init-scripts.
  • Geen informatieschema. Tabellen in het informatieschema voor geheimen zijn nog niet beschikbaar. Gebruik Catalog Explorer of de REST API voor detectie.
  • dbutils runtimebereik. dbutils Retrieval wordt ondersteund voor notebooks en taken die gebruikmaken van Databricks Runtime. Niet-Databricks Runtime-contexten, zoals externe ontwikkeling of gecompileerde JAR-uitvoeringsmodi, worden niet ondersteund.
  • OAuth API-bereik. De Geheimen-API van Unity Catalog is alleen toegankelijk met het unity-catalog OAuth API-bereik. Gebruik de secrets API-scope alleen voor Azure Databricks-geheimen op werkruimteniveau.
  • Quotumlimieten. Maximaal 100 geheimen per schema en 1000 per metastore.
  • Last updated on