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.
• 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 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 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 un entorno de proceso habilitado para Unity Catalog. Azure Databricks recomienda una de las siguientes opciones:
  • Tareas y cuadernos sin servidor que utilicen la versión 4 o superior del entorno.
  • Proceso clásico en modo de acceso estándar que ejecuta Databricks Runtime 17.3 LTS o superior.
• 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:

• 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 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.