Titkos kódok a Unity Katalógusban

Ez az oldal bemutatja, hogyan hozhat létre, olvashat, szabályozhat és kezelhet titkos kulcsokat a Unity Catalogban. A Unity-katalógus titkos kódjai olyan biztonságos objektumok, amelyek bizalmas anyagokat, például jelszót, jogkivonatot vagy API-kulcsot tárolnak. A jegyzetfüzetek és a feladatok a kódban szereplő érték felfedése nélkül hivatkozhatnak a titkos kódra.

A Unity Catalog titkos kódjai a háromszintű névteret (catalog.schema.secret) használják, és a metaadattárhoz csatolt munkaterületeken érhetők el. A Unity Catalog jogosultságai szabályozzák őket. Ez lehetővé teszi, hogy ugyanazt a hozzáférési modellt és auditálást alkalmazza a titkos adataira is, mint amelyet más adateszközeihez használ.

Note

A Unity Catalog titkos kódjai eltérnek a munkaterületszintű Azure Databricks titkos kulcsoktól, amelyek titkos hatókörökbe vannak rendezve. A Unity Catalog titkos kulcsait akkor használja, ha Unity Catalog-jogosultságokkal szeretné szabályozni a titkos kulcsokat, és a háromszintű névtérrel hivatkozni rájuk.

A Unity Catalog titkos kulcsok működése

A Unity Catalog titok egy sémán belüli védhető objektum, amelynek teljesen minősített neve: catalog.schema.secret. A Unity Catalog más biztonságos objektumaihoz hasonlóan a titkos kódok is támogatják a katalógusból és a sémából származó jogosultságöröklést. A biztonságos objektumokról és az öröklésről további információt a Unity Catalog biztonságos objektumokra vonatkozó hivatkozásában talál.

A Unity Catalog titkos kulcsát a következő módokon használhatja:

• Kérje le az értéket a kódban. A READ SECRET hozzáféréssel a felhasználók lekérhetnek egy titkos értéket notebookokból és jobokból a dbutils vagy a Unity Catalog REST API használatával. Ezután használhatják külső rendszerekkel való hitelesítésre, vagy adatok titkosítására és visszafejtésére.
• Hivatkozzon a Unity Catalog-objektumok értékére. A Unity Catalog-objektumok, például a Unity Catalog-kapcsolatok név szerint hivatkozhatnak egy titkos kódra, így az integráció anélkül használhatja a titkos kódot, hogy hozzáférést ad a felhasználóknak az értékhez. Az objektumtól függően a titkos adatra való hivatkozáshoz vagy a(z) REFERENCE SECRET, vagy a(z) READ SECRET szükséges.

Azure Databricks a Unity Catalog titkos értékeit titkosítva tárolja, és titkos kódátadást alkalmaz a kimenetek és naplók véletlen expozíciójának csökkentése érdekében. A titkos kódok elforgatásához rendszeresen frissítse az értékét a felhasználói felületen vagy a Unity Catalog REST API-val.

A Unity Catalog titkos kulcsainak jogosultságai

Az alábbi jogosultságok szabályozzák a titkos adatokat. A katalógus, a séma vagy az egyéni titkos kód szintjén is megadhatóak, és a Unity Catalog jogosultságöröklődését követik.

Kiváltság	Description
CREATE SECRET	Lehetővé teszi a felhasználó számára, hogy titkos kódot hozzon létre egy sémában. Katalógus- vagy sémaszinten megadva.
READ SECRET	Lehetővé teszi, hogy a felhasználó lekérjen egy titkos értéket.
WRITE SECRET	Lehetővé teszi a felhasználó számára egy titkos kód értékének frissítését.
REFERENCE SECRET	Lehetővé teszi a felhasználó számára, hogy az érték elérése nélkül hivatkozzon egy titkos kódra, például egy Unity Catalog-kapcsolatból.

Titkos kód létrehozásához egy sémában a felhasználónak rendelkeznie kell a(z) USE CATALOG engedéllyel, és vagy a séma tulajdonosának kell lennie, vagy rendelkeznie kell a(z) CREATE SECRET és USE SCHEMA engedéllyel a sémára. A jogosultságok megadásának módjáról további információt a Jogosultságok kezelése a Unity Katalógusban című témakörben talál.

Mielőtt hozzákezdene

A Unity Catalog titkos kulcsainak használatához meg kell felelnie az alábbi követelményeknek:

• A munkaterületet engedélyezni kell a Unity Cataloghoz. Bevezetésként lásd : Mi az a Unity Catalog?.
• A titkos adatokhoz Unity Catalog-kompatibilis számítási erőforrásból kell hozzáférnie. Azure Databricks a következők egyikét javasolja:
  • Kiszolgáló nélküli feladatok és jegyzetfüzetek a 4-es vagy újabb környezeti verzióval.
  • Klasszikus számítás standard hozzáférési módban a Databricks Runtime 17.3 LTS vagy újabb verzióját futtatva.
• A titkos kódok dbutilslekéréséhez a számításnak a Databricks Runtime 17.3 LTS vagy újabb verzióját, vagy a kiszolgáló nélküli környezet 4-es vagy újabb verzióját kell futtatnia.

Titkos kulcs létrehozása

A titkos adat létrehozásához USE CATALOG jogosultsággal kell rendelkeznie, és a séma tulajdonosának kell lennie, vagy rendelkeznie kell a sémára vonatkozó CREATE SECRET és USE SCHEMA jogosultsággal. Tekintse meg a Unity Catalog titkos kulcsainak jogosultságait.

Katalóguskezelő

1. A Azure Databricks munkaterületen kattintson a Katalógus gombra a Catalog Explorer megnyitásához.
2. Lépjen arra a sémára, ahol létre szeretné hozni a titkos kulcsot.
3. Kattintson a Titkos kód létrehozása gombra>.
4. Adjon meg egy nevet és egy értéket. Tetszés szerint megjegyzést éslejárati dátumot adhat hozzá. Ha egy titkos kód lejár, a Katalóguskezelő figyelmeztetést jelenít meg.
5. Kattintson a Létrehozás gombra.

REST API

Futtassa a következő cURL-parancsot a /api/2.1/unity-catalog/secrets végpont használatával:

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"

Titkos kulcs beolvasása

Egy titkos érték olvasásához rendelkeznie kell a(z) READ SECRET jogosultsággal a titkos értéken vagy egy felettes katalóguson vagy sémán.

Titkos adatok segédprogram (dbutils.secrets)

Az Azure Databricks a titkos adatok olvasásához a dbutils használatát javasolja, mert alkalmazza a titkos adatok maszkolását. Ehhez a beállításhoz a Databricks Runtime 17.3 LTS vagy újabb verziója, illetve a kiszolgáló nélküli környezet 4-es vagy újabb verziója szükséges.

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

További információ: Titkos kulcsok segédprogram (dbutils.secrets).

REST API

Warning

A Unity Catalog REST API-jával lekért titkos értékekre nem vonatkozik a titkos adatok kitakarása, azonban a hozzáférést továbbra is rögzítik az auditnaplók. Azure Databricks javasolja dbutils inkább.

Az érték visszaadásához állítsa be include_value=true és olvassa el a effective_value mezőt a válaszban:

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

Használj titkot a kódodban

Miután a(z) dbutils.secrets.get használatával beolvasott egy Unity Catalog-titkot, adja át a visszaadott értéket az alkalmazáskódnak. dbutils kitakarja az értéket a cella kimenetében és a naplókban, így anélkül használhatod, hogy felfednéd.

A következő példa egy titkot használ hordójelként egy külső API meghívására:

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()

A következő példa lekér egy titkos értéket, majd átadja azt a dbutils.credentials.getServiceCredentialsProvider számára az AWS SDK boto3-munkamenetének konfigurálásához. A szolgáltatás hitelesítő adatának neve önmagában nem érzékeny, ezért ez a példa csak annak szemléltetésére tárol el egyet egy titokban, hogyan lehet egy lekért titokértéket egy másik SDK-hívásban felhasználni. További információért a szolgáltatási hitelesítésekről lásd: Használd a Unity katalógus szolgáltatási hitelesítő adatokat külső felhőszolgáltatásokhoz való csatlakozáshoz.

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

Titkos kódokra vonatkozó engedélyek kezelése

Adjon CREATE SECRET jogosultságot a katalógus vagy a séma szintjén annak szabályozására, hogy ki hozhat létre titkos adatokat. A hozzáférés szabályozásához adjon READ SECRET, WRITE SECRET vagy REFERENCE SECRET jogosultságot a katalógus, a séma vagy az egyedi titok szintjén. A jogosultságöröklés érvényes. A jogosultságok megadásáról és visszavonásáról további információt a Jogosultságok kezelése a Unity Katalógusban című témakörben talál.

Titkos kulcsok létrehozásának engedélyezése

Katalóguskezelő

1. A Catalog Explorerben lépjen a sémára.

2. Kattintson az Engedélyek fülre .

3. Kattintson az Engedélyezés gombra.

4. Válassza ki azokat a rendszerbiztonsági tagokat, amelyeknek hozzáférést szeretne adni, majd válassza a CREATE SECRET lehetőséget.

   Ha egy azonosító nem rendelkezik USE SCHEMA elemmel, egy figyelmeztetés arra kéri, hogy adja meg azt. USE SCHEMA A sémában lévő titkos adatok létrehozásához is szükség van rá.

5. Kattintson a Megerősítés gombra.

SQL

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

REST API

Futtassa a következő cURL-parancsot a /api/2.1/unity-catalog/permissions/schema/{schema_name} végpont használatával:

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

Hozzáférés biztosítása egy titokhoz

Katalóguskezelő

1. A Katalóguskezelőben lépjen a titkos kódra, és kattintson rá.
2. Kattintson az Engedélyek fülre .
3. Kattintson az Engedélyezés gombra.
4. Jelölje ki a felhasználókat és csoportokat, valamint az engedélyezni kívánt jogosultságokat, majd kattintson a Megerősítés gombra.

SQL

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

REST API

Futtassa a következő cURL-parancsot a /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} végpont használatával:

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

Titkos kulcsok listázása, frissítése és törlése

Titkok listázása

Katalóguskezelő

1. A Catalog Explorerben lépjen a sémára.
2. Az Áttekintés panelen kattintson a Titkos kulcsok elemre a séma összes titkos kulcsának megtekintéséhez.

Titkos adatok segédprogram (dbutils.secrets)

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

REST API

Használd page_size az oldalonkénti eredmények számának szabályozására. Ha további eredmények állnak rendelkezésre, a válasz tartalmazza a következőket 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"

A következő oldal lekéréséhez adja át az előző válaszban kapott next_page_token értéket page_token paraméterként:

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"

Titkos kód frissítése

A secret értékének frissítéséhez rendelkeznie kell WRITE SECRET jogosultsággal a secreten.

Katalóguskezelő

1. A Katalóguskezelőben lépjen a sémára, és kattintson a Titkos kulcsok elemre az Áttekintés panelen.
2. Kattintson a frissíteni kívánt titkos kódra.
3. A jobb felső sarokban kattintson a kebab menüre (függőleges pont), és válassza a Szerkesztés lehetőséget.
4. Adjon meg egy új értéket vagy lejárati dátumot, majd kattintson a Megerősítés gombra.

REST API

A frissítési kérelmekhez szükség van a paraméterre update_mask . Csak az update_mask és a kérés törzsében is szereplő mezők frissülnek:

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

Titkos kulcs törlése

Katalóguskezelő

1. A Katalóguskezelőben lépjen a sémára, és kattintson a Titkos kulcsok elemre az Áttekintés panelen.
2. Kattintson a törölni kívánt titkos kódra.
3. A jobb felső sarokban kattintson a kebab menüre (függőleges pont), és válassza a Törlés lehetőséget.
4. Adja meg a titkos kód teljes nevét, majd kattintson a Törlés gombra.

REST API

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

A Unity Catalog titkaihoz kapcsolódó auditnapló-események

A system.access.audit rendszertábla rögzíti a Unity Catalog titkos kulcsaihoz kapcsolódó eseményeket. Ha például egy felhasználó titkos eseményeit egy adott dátumon szeretné megtekinteni, futtassa a következő lekérdezést:

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

Az auditnaplókkal kapcsolatos további információkért tekintse meg az Auditnapló rendszer táblahivatkozását.

Titkos értékek titkosítása ügyfél által felügyelt kulcsokkal

Alapértelmezés szerint Azure Databricks titkos értékeket titkosít a Databricks által felügyelt kulcsokkal. Ehelyett használhat ügyfél által felügyelt kulcsokat (CMK). Ha engedélyezi a CMK által titkosított felügyelt katalógus funkciót, és CMK-konfigurációt csatol a fiókjához, Azure Databricks a CMK használatával titkosítja a titkos értékeket. További információkért tekintse meg a Unity Catalog ügyfél által felügyelt kulcsait.

Titkok kezelése külső titokkezelővel

Ahelyett, hogy az Azure Databricks tárolná a titkos értékeket, egy sémát külső titkos menedzserrel is vissza lehet zárni, így az értékek a felhő titkos menedzserében maradnak, miközben a Unity Catalogban irányíthatók maradnak. Az AWS Secrets Manager az AWS-en és a Azure Key Vault az Azure-on támogatott. A külső titkok működéséről lásd a Külső titkok a Unity Catalog részt. A séma külső titkos menedzserrel való támogatásához lásd: Külső titkok konfigurálása a Unity katalógusban.

Limitations

A Unity Catalog titkos kódjaira a következő korlátozások vonatkoznak:

• Nincsenek SQL-tárolók. A Unity Catalog titkos kódjai nem támogatottak az SQL-raktárakban. A Databricks Runtime 17.3 LTS-t vagy újabb verziót igényelnek Unity Catalog-kompatibilis számításon vagy kiszolgáló nélkülien.
• Nincs globális felderítés. A Unity-katalógus titkos kódjai nem jelennek meg a globális keresésben.
• Nincs BROWSE engedélytámogatás. BROWSE egy katalógusra nem vonatkozik a Unity Catalog titkaira. Ahhoz, hogy a titok felderíthető legyen, adja meg a READ SECRET vagy REFERENCE SECRET jogosultságot az adott titokra vagy annak sémájára.
• Nincsenek init szkriptek. A Unity Catalog titkos kulcsait nem használhatja globális vagy fürtbeli init szkriptekben. Azure Databricks ajánlott a dedikált funkciók használata az init szkriptek helyett, ahol lehetséges.
• Nincs információséma. A titkos kódokhoz tartozó információs sématáblák még nem érhetők el. A Katalóguskezelő vagy a REST API használata a felderítéshez.
• dbutils futásidejű hatókör.A dbutils lekérése támogatott a Databricks Runtime által támogatott jegyzetfüzetekben és feladatokban. A nem Databricks Runtime-környezetek, például a távoli fejlesztés vagy a lefordított JAR-futtatási módok nem támogatottak.
• OAuth API-hatókör. A Unity Catalog titkos kulcsok API-ja csak az unity-catalog OAuth API hatókörével érhető el. secrets Az API-hatókört csak munkaterületszintű Azure Databricks titkos kódokhoz használja.
• Kvótakorlátok. Sémánként legfeljebb 100 titkos kód, metaadattáronként pedig 1000 titkos kód.