Secretos en el catálogo de Unity

Importante

Esta característica está en versión preliminar pública.

En esta página se describe cómo crear, leer, controlar y administrar secretos en el catálogo de Unity. Un secreto del catálogo de Unity es un objeto protegible que almacena material confidencial, como una contraseña, un token o una clave de API. Tus cuadernos y tareas pueden hacer referencia a un secreto sin exponer su valor en el código fuente.

Los secretos de Unity Catalog usan el espacio de nombres de tres niveles (catalog.schema.secret) y están disponibles en los espacios de trabajo vinculados a un metastore. Los privilegios del catálogo de Unity los rigen. Esto le permite aplicar a sus secretos el mismo modelo de acceso y auditoría que utiliza para otros activos de datos.

Note

Los secretos del catálogo de Unity son distintos de los secretos de nivel de área de trabajo Azure Databricks, que se organizan en ámbitos secretos. Utilice los secretos de Unity Catalog cuando desee administrar secretos con los privilegios de Unity Catalog y hacer referencia a ellos mediante el espacio de nombres de tres niveles.

Cómo funcionan los secretos de Unity Catalog

Un secreto de Unity Catalog es un objeto protegible dentro de un esquema, con el nombre completo catalog.schema.secret. Al igual que otros objetos protegibles de Unity Catalog, los secretos admiten la herencia de privilegios desde el catálogo y el esquema. Para obtener más información sobre los objetos protegibles y la herencia, consulte Referencia de objetos protegibles del catálogo de Unity.

Puede usar un secreto de catálogo de Unity de las maneras siguientes:

  • Recupere el valor en el código. Con acceso READ SECRET, los usuarios pueden recuperar un valor secreto de notebooks y trabajos usando dbutils o la API REST de Unity Catalog. Después, pueden usarlo para autenticarse con sistemas externos o para cifrar y descifrar datos.
  • Haga referencia al valor de los objetos de Unity Catalog. Los objetos de Unity Catalog, como las conexiones de Unity Catalog, pueden hacer referencia a un secreto mediante su nombre para que una integración pueda usar el secreto sin conceder a los usuarios acceso a su valor. Según el objeto , hacer referencia a un secreto requiere REFERENCE SECRET o READ SECRET.

Azure Databricks almacena cifrados los valores secretos de Unity Catalog y aplica la redacción de secretos para reducir la exposición accidental en los resultados y registros. Para rotar un secreto, actualice periódicamente su valor en la interfaz de usuario o con la API REST del catálogo de Unity.

Privilegios de los secretos de Unity Catalog

Los siguientes privilegios rigen los secretos. Puede otorgarlos a nivel de catálogo, esquema o secreto individual, y siguen la herencia de privilegios de Unity Catalog.

Privilegio Descripción
CREATE SECRET Permite a un usuario crear un secreto en un esquema. Otorgado en el nivel de catálogo o del esquema.
READ SECRET Permite que un usuario recupere un valor secreto.
WRITE SECRET Permite a un usuario actualizar un valor secreto.
REFERENCE SECRET Permite que un usuario haga referencia a un secreto, por ejemplo, desde una conexión de catálogo de Unity, sin acceso al valor.

Para crear un secreto en un esquema, un usuario debe tener USE CATALOG permiso y poseer el esquema o tener CREATE SECRET y USE SCHEMA en el esquema. Para obtener información sobre cómo conceder privilegios, consulte Administrar privilegios en el catálogo de Unity.

Antes de empezar

Para usar secretos del catálogo de Unity, debe cumplir los siguientes requisitos:

  • El área de trabajo debe estar habilitada para el catálogo de Unity. Para obtener una introducción, consulte ¿Qué es el catálogo de Unity?.
  • Debe acceder a los secretos desde recursos de proceso habilitados para Unity Catalog. Azure Databricks recomienda una de las siguientes opciones:
  • Para recuperar secretos con dbutils, el proceso debe ejecutar Databricks Runtime 17.3 LTS o superior, o la versión 4 o superior del entorno sin servidor.

Crear un secreto

La creación de un secreto requiere que tenga el permiso USE CATALOG y sea el propietario del esquema, o que tenga CREATE SECRET y USE SCHEMA sobre el esquema. Consulte Privilegios para secretos de Unity Catalog.

Explorador de catálogos

  1. En el área de trabajo de Azure Databricks, haga clic en Catálogo para abrir el Explorador de catálogos.
  2. Vaya al esquema donde desea crear el secreto.
  3. Haga clic en Crear > secreto.
  4. Escriba un nombre y un valor. Opcionalmente, agregue un comentario y una fecha de expiración. Si expira un secreto, el Explorador de catálogos muestra una advertencia.
  5. Haga clic en Crear.

REST API

Ejecute el siguiente comando cURL mediante el /api/2.1/unity-catalog/secrets punto de conexión:

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"

Descifrar un secreto

Para leer un valor secreto, debe tener READ SECRET en el secreto o en un catálogo o esquema primarios.

Utilidad de secretos (dbutils.secrets)

Azure Databricks recomienda usar dbutils para leer secretos, ya que aplica el enmascaramiento de secretos. Esta opción requiere Databricks Runtime 17.3 LTS o superior, o la versión 4 o superior del entorno sin servidor.

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

Para obtener más información, vea Utilidad secretos (dbutils.secrets).

REST API

Warning

Los valores secretos recuperados con la API REST de Unity Catalog no están sujetos a la ocultación de secretos, aunque el acceso sigue registrándose en los registros de auditoría. Azure Databricks recomienda dbutils en su lugar.

Para devolver el valor, establezca include_value=true y lea el effective_value campo en la respuesta:

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

Administrar permisos de secretos

Conceda CREATE SECRET en el nivel de catálogo o esquema para controlar quién puede crear secretos. Otorgue READ SECRET, WRITE SECRET o REFERENCE SECRET a nivel de catálogo, esquema o secreto individual para controlar el acceso. Se aplica la herencia de privilegios. Para más información sobre cómo conceder y revocar privilegios, consulte Administrar privilegios en el catálogo de Unity.

Concesión de la capacidad de crear secretos

Explorador de catálogos

  1. En el Explorador de catálogos, vaya al esquema.

  2. Haga clic en la pestaña Permisos.

  3. Haga clic en Permitir.

  4. Seleccione las identidades a las que desea conceder acceso y, a continuación, seleccione CREATE SECRET.

    Si una entidad de seguridad no tiene USE SCHEMA, aparecerá una advertencia para que lo conceda. También se requiere USE SCHEMA para crear secretos en el esquema.

  5. Haga clic en Confirmar.

SQL

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

REST API

Ejecute el siguiente comando cURL mediante el /api/2.1/unity-catalog/permissions/schema/{schema_name} punto de conexión:

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

Concesión de acceso a un secreto

Explorador de catálogos

  1. En el Explorador de catálogos, vaya al secreto y haga clic en él.
  2. Haga clic en la pestaña Permisos.
  3. Haga clic en Permitir.
  4. Seleccione las entidades de seguridad y los privilegios que desea conceder, y haga clic en Confirmar.

SQL

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

REST API

Ejecute el siguiente comando cURL mediante el /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} punto de conexión:

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

Enumerar, actualizar y eliminar secretos

Enumerar secretos

Explorador de catálogos

  1. En el Explorador de catálogos, vaya al esquema.
  2. En el panel Información general , haga clic en Secretos para ver todos los secretos en el esquema.

Utilidad de secretos (dbutils.secrets)

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

REST API

Las solicitudes de lista usan page_size para controlar el número de resultados:

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"

Actualización de un secreto

Para actualizar un valor secreto, debe tener WRITE SECRET en el secreto.

Explorador de catálogos

  1. En el Explorador de catálogos, vaya al esquema y haga clic en Secretos en el panel Información general .
  2. Haga clic en el secreto para actualizar.
  3. En la esquina superior derecha, haga clic en el menú kebab (puntos verticales) y seleccione Editar.
  4. Escriba un nuevo valor o fecha de expiración y haga clic en Confirmar.

REST API

Las solicitudes de actualización requieren el update_mask parámetro . Solo se actualizan los campos incluidos tanto en update_mask como en el cuerpo de la solicitud:

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

Elimina un secreto

Explorador de catálogos

  1. En el Explorador de catálogos, vaya al esquema y haga clic en Secretos en el panel Información general .
  2. Haga clic en el secreto que desea eliminar.
  3. En la esquina superior derecha, haga clic en el menú kebab (puntos verticales) y seleccione Eliminar.
  4. Escriba el nombre completo del secreto y haga clic en Eliminar.

REST API

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

Eventos de auditoría de los secretos de Unity Catalog

La system.access.audit tabla del sistema registra eventos relacionados con los secretos del catálogo de Unity. Por ejemplo, para ver todos los eventos secretos de un usuario en una fecha específica, ejecute la consulta siguiente:

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

Para obtener más información sobre los registros de auditoría, consulte Referencia de tabla del sistema de registro de auditoría.

Cifrado de valores secretos con claves administradas por el cliente

De forma predeterminada, Azure Databricks cifra los valores secretos con claves administradas por Databricks. En su lugar, puede usar claves administradas por el cliente (CMK). Si habilita la característica de catálogo administrado cifrado por CMK y adjunta una configuración de CMK a su cuenta, Azure Databricks usa cmK para cifrar los valores secretos. Para obtener más información, consulte Claves administradas por el cliente para el catálogo de Unity.

Limitaciones

Los secretos del catálogo de Unity tienen las siguientes limitaciones:

  • No hay almacenes de SQL. Los secretos del catálogo de Unity no se admiten en almacenes de SQL. Requieren Databricks Runtime 17.3 LTS o superior en cómputo habilitado para Unity Catalog o sin servidor.
  • No hay ninguna detección global. Los secretos del catálogo de Unity no aparecen en la búsqueda global.
  • No compatible con el permiso BROWSE. BROWSE en un catálogo no se aplica a los secretos de Unity Catalog. Para que un secreto sea visible, conceda READ SECRET o REFERENCE SECRET sobre el secreto individual o sobre su esquema.
  • No hay scripts de inicialización. No puede usar secretos del catálogo de Unity en scripts de inicialización globales o de clúster. Azure Databricks recomienda usar características dedicadas en lugar de scripts de inicialización siempre que sea posible.
  • Sin esquema de información. Las tablas del esquema de información de secretos aún no están disponibles. Use el Explorador de catálogos o la API REST para la detección.
  • dbutils ámbito de ejecución. dbutils la recuperación se admite en cuadernos y trabajos respaldados por Databricks Runtime. No se admiten contextos en tiempo de ejecución que no son de Databricks, como el desarrollo remoto o los modos de ejecución jar compilados.
  • Ámbito de la API de OAuth. La API de secretos de Unity Catalog solo es accesible con el ámbito de OAuth API unity-catalog. Use el ámbito de API secrets solo para secretos de Azure Databricks de nivel de área de trabajo.
  • Límites de cuota. Hasta 100 secretos por esquema y 1000 por metastore.
  • Last updated on