Secretos en el catálogo de Unity

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 el READ SECRET acceso, los usuarios pueden recuperar un valor secreto de cuadernos y trabajos mediante dbutils o la API REST de Unity Catalog. Después, pueden usarlo para autenticarse con sistemas externos o para cifrar y descifrar datos.
  • Utiliza el valor en un UDF de Python o Scala con alcance de sesión. Véase UDFs con alcance de sesión.
  • Utiliza el valor en un UDF de Python del Unity Catalog. Un UDF escalar o por lotes declara cada secreto en su SECRETS cláusula. Consulta los UDFs de Python.
  • Usa el valor en un UDF Scala de Unity Catalog. Una UDF escalar declara cada secreto en la cláusula SECRETS. Consulta los UDFs de Scala.

Para el comportamiento de requisitos y permisos entre tipos de UDF, consulte Requisitos y permisos de UDF.

Los UDFs pueden utilizar secretos gestionados por Azure Databricks o secretos respaldados por un gestor de secretos externo. Consulta secretos externos en Unity Catalog.

Requisitos y permisos de la UDF

Los requisitos y el comportamiento de permisos varían entre los UDF con alcance de sesión y los UDF de Unity Catalog.

UDFs con alcance de sesión

Un UDF de Python con alcance de sesión recupera un secreto con databricks.secrets.get(), y un UDF de Scala con alcance de sesión recupera uno con com.databricks.Secrets.get(). El acceso secreto utiliza los permisos del llamante.

Los requisitos de cómputo para el acceso secreto dependen del lenguaje UDF:

  • En la computación sin servidor, el cuaderno o la sesión de trabajo programado deben usar la versión 6 o superior del entorno para las funciones definidas por el usuario (UDF) de Python y Scala.
  • En el cómputo clásico, las UDF de Python con ámbito de sesión requieren Databricks Runtime 19 o superior en el modo de acceso estándar o dedicado.
  • En el proceso clásico, las UDF de Scala de ámbito de sesión requieren Databricks Runtime 19 o posterior y el modo de acceso estándar.

UDF de Unity Catalog

Las UDF de Python de Unity Catalog, escalares y por lotes, y las UDF escalares de Scala de Unity Catalog declaran secretos en la cláusula SECRETS y deben establecer explícitamente environment_version en 6 o un valor superior. Admiten procesamiento sin servidor, almacenes SQL sin servidor y procesamiento clásico que ejecuta Databricks Runtime 19 o superior con el modo de acceso estándar.

Los almacenes Pro SQL soportan UDFs Python escalares y Batch Unity Catalog que usan secretos. Los UDFs Scala de Unity Catalog que usan secretos no son compatibles con almacenes SQL profesionales.

Para crear o reemplazar una UDF que declare un secreto, la entidad principal que ejecuta la instrucción debe tener READ SECRET sobre el secreto y USE CATALOG y USE SCHEMA sobre su catálogo y esquema primario. En tiempo de ejecución, la UDF utiliza los permisos del propietario actual de la función. Los llamantes necesitan los privilegios funcionales habituales, incluyendo EXECUTE, pero no necesitan acceso directo a los secretos declarados. Si el propietario de la función pierde permiso para leer un secreto declarado, la UDF falla.

Utilice UDF habilitadas para secretos en máscaras de columna en proceso dedicado

No puedes invocar directamente una UDF de Python o Scala de Unity Catalog que use la cláusula SECRETS en un recurso de cómputo con modo de acceso dedicado. Sin embargo, puedes crear una función SQL de Unity Catalog que llame a la UDF con acceso a secretos y usar la función SQL como máscara de columna para el control de acceso basado en atributos (ABAC). Cuando una consulta se ejecuta en computación dedicada, Azure Databricks delega la aplicación de la máscara de columna al computo sin servidor. Esta excepción solo se aplica al aplicar la máscara de columna; no permite la invocación directa del UDF habilitado para secreto en el cómputo dedicado. Véase Versiones de cómputo no soportadas.

Warning

Utiliza valores secretos solo dentro de la implementación de la UDF. No devuelvas valores secretos ni los incluyas en los resultados de la UDF. La redacción secreta ayuda a reducir la exposición accidental en errores y registros, pero no impide que el código UDF exponga material secreto en los resultados de la consulta.

Azure Databricks almacena los valores secretos de Unity Catalog cifrados y aplica la ocultación de secretos para reducir la exposición accidental en los resultados y los 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 para los secretos de Unity Catalog

Los siguientes privilegios rigen los secretos. Puede concederlos en el 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. Concedidos en el nivel de catálogo o esquema.
READ SECRET Permite que un usuario recupere un valor secreto.
WRITE SECRET Permite a un usuario actualizar un valor secreto.
REFERENCE SECRET Permite a un usuario referenciar un secreto 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.

Requirements

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 un entorno de proceso habilitado para Unity Catalog. Azure Databricks recomienda una de las siguientes opciones:
  • Para recuperar secretos con dbutils, el entorno de proceso debe ejecutar Databricks Runtime 17.3 LTS o superior, o un entorno sin servidor versión 4 o superior.

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 el valor de un secreto, debe tener READ SECRET en el secreto o en un catálogo o esquema principal.

Utilidad de secretos (dbutils.secrets)

Azure Databricks recomienda dbutils para leer secretos, ya que aplica la ocultación 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 de los secretos recuperados mediante 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"

Usa un secreto en tu código

Después de leer un secreto del Catálogo de Unity con dbutils.secrets.get, pasa el valor devuelto al código de tu aplicación. dbutils oculta el valor en la salida de la celda y en los registros, por lo que puedes usarlo sin exponerlo.

El siguiente ejemplo utiliza un secreto como token portador para llamar a una API externa:

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

El siguiente ejemplo recupera un valor secreto y lo pasa a dbutils.credentials.getServiceCredentialsProvider para configurar una sesión de boto3 para AWS SDK. El nombre de una credencial de servicio no es en sí mismo un dato sensible, por lo que este ejemplo lo almacena en un secreto únicamente para ilustrar cómo encadenar el valor recuperado de ese secreto en otra llamada al SDK. Para más información sobre credenciales de servicio, consulte Usar credenciales de servicio del Catálogo Unity para conectarse a servicios en la nube externos.

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

Administrar permisos sobre los 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. Selecciona los sujetos a los que deseas conceder acceso y, a continuación, selecciona CREAR SECRETO.

    Si un sujeto no tiene USE SCHEMA, aparecerá una advertencia pidiéndote que se lo concedas. 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. Selecciona los sujetos y los privilegios que deseas conceder y, a continuación, haz 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

Úsalo page_size para controlar el número de resultados por página. Si hay más resultados disponibles, la respuesta incluye un 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"

Para recuperar la siguiente página, pasa el next_page_token valor de la respuesta anterior como parámetro page_token :

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"

Actualización de un secreto

Para actualizar el valor de un secreto, debes tener WRITE SECRET sobre dicho 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 para 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.

Respalda los secretos con un gestor de secretos externo

En lugar de que Azure Databricks almacene valores secretos, puedes respaldar un esquema con un gestor de secretos externo para que los valores permanezcan en tu gestor de secretos en la nube mientras permanecen gobernables en Unity Catalog. AWS Secrets Manager en AWS y Azure Key Vault en Azure son compatibles. Para saber cómo funcionan los secretos externos, véase Secretos externos en el Catálogo de Unity. Para respaldar un esquema con un gestor de secretos externo, consulte Configurar secretos externos en el Catálogo de Unity.

Limitaciones

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

  • Acceso directo limitado desde almacenes SQL. No puedes recuperar los secretos del Catálogo de Unity directamente de los almacenes SQL. Las UDF de Python escalares y por lotes de Unity Catalog pueden acceder a secretos declarados en sus cláusulas SECRETS en almacenes SQL Pro y sin servidor. Las UDF escalares de Scala de Unity Catalog solo pueden acceder a los secretos declarados en almacenes SQL sin servidor.
  • No hay invocación directa SECRETS de UDF en computación dedicada. No puedes invocar directamente UDF de Python de Unity Catalog, ya sean escalares o por lotes, ni UDF escalares de Scala de Unity Catalog que usen la cláusula SECRETS en el cómputo con modo de acceso dedicado. Para la excepción de la máscara de columna, consulte Uso de UDF con secretos habilitados en máscaras de columna en proceso dedicado.
  • No hay ninguna detección global. Los secretos del catálogo de Unity no aparecen en la búsqueda global.
  • No se admite el permiso BROWSE. BROWSE en un catálogo no se aplica a los secretos de Unity Catalog. Para que un secreto sea detectable, conceda READ SECRET o REFERENCE SECRET en el secreto individual o en 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. La recuperación de dbutils es compatible con los 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. Utilice el ámbito de la API secrets únicamente para secretos de Azure Databricks en el nivel de espacio de trabajo.
  • Límites de cuota. Hasta 100 secretos por esquema y 1000 por metastore.
  • Última actualización el