Configuración de la autorización en una aplicación de Databricks

Databricks Apps admite el desarrollo seguro de aplicaciones en Azure Databricks. A medida que las aplicaciones acceden a datos y servicios dentro de un área de trabajo, deben usar mecanismos de autenticación y autorización que apliquen controles de acceso a datos y respeten los permisos de usuario. El modelo de autorización de Aplicaciones de Databricks se basa en OAuth 2.0 y combina los permisos asignados a la aplicación con los del usuario que acceden a ella.

Para admitir este marco, Databricks Apps usa dos modelos de identidad complementarios:

• La autorización de la aplicación proporciona a la aplicación su propia identidad con un conjunto coherente de permisos.
• La autorización de usuario permite a la aplicación usar la identidad y los permisos del usuario que interactúa con ella.

Autorización de la aplicación

Cada aplicación de Azure Databricks tiene un service principal dedicado que actúa como su identidad cuando accede a los recursos de Azure Databricks. Esta entidad de servicio es única para la instancia de la aplicación y no se puede reutilizar en todas las aplicaciones. No se puede cambiar la entidad de servicio asignada a una aplicación ni especificar una entidad de servicio existente durante la creación de la aplicación. Azure Databricks usa esta identidad para evaluar los permisos de la aplicación independientemente de cualquier usuario, lo que garantiza que la aplicación solo pueda acceder a los recursos concedidos explícitamente, incluso fuera del contexto de interacción del usuario.

Esta separación ayuda a aplicar límites de seguridad, lo que permite la auditoría de la actividad de la aplicación y admite escenarios como el procesamiento en segundo plano o las tareas automatizadas.

La entidad de servicio se representa mediante un identificador único. Cópielo desde la pestaña Autorización de la aplicación:

Al crear una aplicación, Azure Databricks aprovisiona automáticamente una entidad de servicio dedicada para la aplicación. La entidad de servicio (service principal) sigue siendo la misma en todas las implementaciones de la aplicación. Al eliminar la aplicación, Azure Databricks elimina el principal de servicio.

Utiliza el servicio principal para las acciones que realiza la aplicación por su cuenta, sin requerir el contexto de un usuario individual. Entre los casos de uso comunes se incluye:

• Ejecución de tareas en segundo plano
• Lectura o escritura de metadatos o configuración compartida
• Registro de métricas de uso o actividad
• Llamada a servicios externos a través de puntos de conexión seguros

Todas las acciones iniciadas por la aplicación usan los permisos de la entidad de servicio. Conceda al principal de servicio acceso a recursos específicos utilizando asignaciones estándar de permisos. Sin embargo, no admite el control de acceso de nivel de usuario. Todos los usuarios que interactúan con la aplicación comparten los mismos permisos definidos para la entidad de servicio, lo que impide que la aplicación aplique directivas específicas basadas en la identidad de usuario individual.

En el ejemplo siguiente se muestra cómo una aplicación usa el principal del servicio para consultar datos en Unity Catalog.

En este caso, la entidad de servicio necesita acceso explícito tanto al almacén de datos SQL como a la tabla del Catálogo de Unity que consulta.

Este modelo funciona bien cuando desea que todos los usuarios de la aplicación vean los mismos datos o cuando la aplicación realiza operaciones compartidas no vinculadas a controles de acceso específicos del usuario.

Recuperación de credenciales de autorización de aplicaciones

Para la autorización de aplicaciones, Azure Databricks inserta automáticamente credenciales de entidad de servicio en el entorno de la aplicación. Las siguientes variables de entorno contienen los valores de cliente de OAuth necesarios:

Variable	Description
DATABRICKS_CLIENT_ID	Id. del cliente OAuth de la entidad de servicio
DATABRICKS_CLIENT_SECRET	Secreto de cliente OAuth de la entidad de servicio

Azure Databricks establece automáticamente las variables de entorno en el entorno de ejecución de la aplicación. La aplicación usa estas variables cuando se autentica como sí misma.

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

JavaScript

const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;

Note

Si usa los SDK de Azure Databricks, normalmente no es necesario acceder manualmente a estas variables de entorno. Los SDK siguen la autenticación unificada y detectan automáticamente las credenciales en el entorno.

Ejemplo: Consulta con autorización de aplicación

Python

En este ejemplo se usa el objeto Config del SDK, que extrae las credenciales de entidad de servicio de las variables de entorno y realiza la autorización de OAuth.

from databricks import sql
from databricks.sdk.core import Config

cfg = Config()

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    credentials_provider=lambda: cfg.authenticate,
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

En este ejemplo se usan variables de entorno para autenticarse con una entidad de servicio mediante OAuth y ejecutar una consulta con databricks SQL Driver for Node.js.

import { DBSQLClient } from '@databricks/sql';

const client = new DBSQLClient();

const connection = await client.connect({
  authType: 'databricks-oauth',
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  oauthClientId: process.env.DATABRICKS_CLIENT_ID,
  oauthClientSecret: process.env.DATABRICKS_CLIENT_SECRET,
});

const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
const cursor = await connection.cursor(query);

const rows = [];
for await (const row of cursor) {
  rows.push(row);
}

console.log(rows.slice(0, 5)); // Like df.head()

await connection.close();

Autorización de usuario

Important

La autorización de usuario está en versión preliminar pública.

La autorización de usuario, a veces denominada autorización en nombre del usuario, permite que una aplicación de Databricks Apps actúe con la identidad del usuario de la aplicación. Azure Databricks reenvía el token de acceso del usuario a la aplicación, que usa el token para acceder a los recursos en nombre del usuario. Azure Databricks aplica todos los permisos en función de las directivas de catálogo de Unity existentes del usuario.

Para administrar los riesgos de seguridad de las aplicaciones que actúan en nombre de un usuario, Azure Databricks usa ámbitos para limitar las acciones que una aplicación puede realizar a través de la autorización del usuario.

Aplique la autorización de usuario cuando la aplicación necesite respetar los permisos de usuario individuales. Entre los casos de uso típicos se incluyen:

• Consulta de tablas o volúmenes
• Acceso a almacenes o procesos de SQL
• Ejecución de trabajos o flujos de trabajo vinculados a acciones de usuario

Todas las acciones usan los permisos existentes del catálogo de Unity del usuario:

La autorización de usuario permite el control de acceso específico mediante la aplicación de características del catálogo de Unity, como filtros de nivel de fila y máscaras de columna a la actividad de la aplicación. Este enfoque mantiene el control de acceso coherente con la gobernanza del área de trabajo y evita la lógica de permisos de codificación dura en la aplicación.

Permisos específicos con autorización de usuario

Cuando se agrega autorización de usuario a una aplicación, se aplican los permisos existentes del catálogo de Unity del usuario, incluidos:

• Filtros de nivel de fila para restringir las filas visibles
• Máscaras de columna para redactar o transformar datos sensibles

Dado que Azure Databricks evalúa las solicitudes de autorización de usuario con la identidad del usuario, estas directivas se aplican automáticamente cuando la aplicación accede a los datos. Por ejemplo, si una tabla incluye un filtro de fila que limita la visibilidad por región, la aplicación solo devuelve las filas que el usuario puede consultar. No se necesita ninguna lógica de filtrado adicional en la aplicación.

Este enfoque evita duplicar la lógica de control de acceso en el código de aplicación y garantiza la coherencia con la gobernanza de nivel de área de trabajo. Cuando los administradores actualizan las directivas de catálogo de Unity, la aplicación respeta automáticamente esos cambios.

Seguridad basada en ámbito y escalación de privilegios

Las aplicaciones que usan la autorización de usuario deben declarar ámbitos de autorización específicos para limitar lo que la aplicación puede hacer en nombre del usuario. Los ámbitos restringen el acceso a api o tipos de recursos específicos, como:

• sql para consultar almacenes de SQL
• dashboards.genie para gestionar su espacio Genie
• files.files para administrar los archivos y directorios

Si no selecciona ningún ámbito, Azure Databricks asigna un conjunto predeterminado que permite a la aplicación recuperar información básica de identidad de usuario:

• iam.access-control:read
• iam.current-user:read

Estos valores predeterminados son necesarios para admitir la funcionalidad de autorización de usuario, pero no permiten el acceso a los datos ni a los recursos de proceso. Agregue ámbitos adicionales al crear o editar la aplicación.

Los alcances imponen el principio de privilegios mínimos. Asegúrese de configurar la aplicación para solicitar solo los ámbitos que necesita. Azure Databricks bloquea el acceso a cualquier funcionalidad fuera de los ámbitos aprobados, incluso si el usuario tiene permiso. Por ejemplo, si la aplicación solicita solo el ámbito sql, no puede acceder a los puntos de conexión de servicio del modelo, incluso si el usuario puede hacerlo fuera de la aplicación.

Cuando un usuario accede por primera vez a una aplicación, Azure Databricks le pide que autorice explícitamente a la aplicación a actuar dentro de los ámbitos solicitados. Opcionalmente, los administradores pueden conceder consentimiento en nombre de los usuarios para alinear el acceso con las directivas de la organización.

Adición de ámbitos a una aplicación

Important

La autorización de usuario está en versión preliminar pública. El administrador del área de trabajo debe habilitarlo para poder agregar ámbitos a la aplicación.

Después de habilitar la autorización de usuario, debe reiniciar las aplicaciones existentes para poder agregar ámbitos a ellas. Si deshabilita la autorización de usuario, debe reiniciar las aplicaciones existentes para que dejen de usar el token de acceso del usuario actual para acceder a los recursos.

Configure la autorización de usuario al crear o editar una aplicación en la interfaz de usuario de Azure Databricks.

En el paso Configurar , haga clic en +Agregar ámbito y seleccione los ámbitos que definen qué API o recursos de Azure Databricks a los que la aplicación puede acceder en nombre del usuario. Azure Databricks aplica estos ámbitos en tiempo de ejecución y requiere el consentimiento del usuario o administrador antes de conceder acceso.

Para obtener un ejemplo completo, consulte la demostración de autorización de Databricks Apps en GitHub. En la aplicación de ejemplo se muestra cómo usar los modelos de autorización de aplicaciones y usuarios, e incluye instrucciones de configuración y consultas de ejemplo con autorización de usuario.

Recuperación de credenciales de autorización de usuario

Para la autorización de usuario, Azure Databricks reenvía la identidad y el token de acceso del usuario a la aplicación en encabezados HTTP. La aplicación debe extraer estos encabezados para actuar en nombre del usuario.

La forma de recuperar estos encabezados depende del marco que use.

Streamlit

import streamlit as st
user_access_token = st.context.headers.get('x-forwarded-access-token')

Gradio

import gradio as gr

def query_fn(message, history, request: gr.Request):
    access_token = request.headers.get("x-forwarded-access-token")
    ...

Gradio inserta automáticamente el objeto de solicitud en la función de la aplicación si lo declaras como parámetro. No tiene que construir ni obtener la solicitud manualmente.

Guión y Flask

from flask import request

headers = request.headers
user_token = headers.get('x-forwarded-access-token')

Shiny

user_token = session.http_conn.headers.get('x-forwarded-access-token')

Express

import express from 'express';

const userAccessToken = req.header('x-forwarded-access-token');

Ejemplo: Consulta con autorización de usuario

En este caso, la aplicación pasa el token de acceso del usuario directamente al conector y Azure Databricks aplica los permisos del usuario a la consulta.

Python

from databricks import sql
from databricks.sdk.core import Config
from flask import request

cfg = Config()
user_token = request.headers.get("x-forwarded-access-token")

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    access_token=user_token
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

import { DBSQLClient } from '@databricks/sql';
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  const userToken = req.header('x-forwarded-access-token');

  const client = new DBSQLClient();
  const connection = await client.connect({
    authType: 'access-token',
    host: process.env.DATABRICKS_SERVER_HOSTNAME,
    path: process.env.DATABRICKS_HTTP_PATH,
    token: userToken,
  });

  const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
  const cursor = await connection.cursor(query);

  const rows = [];
  for await (const row of cursor) {
    rows.push(row);
  }

  console.log(rows.slice(0, 5));
  await connection.close();

  res.send('Query complete');
});

app.listen(3000);

Procedimientos recomendados para la autorización de usuarios

Al compilar aplicaciones que realizan acciones en nombre de los usuarios, siga estos procedimientos recomendados para garantizar el acceso seguro y auditable:

• Almacene el código de la aplicación en carpetas accesibles solo para el propietario de la aplicación o un pequeño conjunto de usuarios de confianza.
• Conceda CAN MANAGE permisos solo a los desarrolladores senior de confianza responsables del mantenimiento y la revisión de aplicaciones. Conceda CAN USE permisos solo a usuarios o grupos específicos que estén aprobados para ejecutar la aplicación.
• Asegúrese de que los tokens no se imprimen, registran ni escriben en archivos. Esto se aplica a todas las instrucciones de registro, las herramientas de depuración y los controladores de errores. Por ejemplo, en lugar de print(f"User token: {token}") usar headers = {"Authorization": f"Bearer {token}"}.
• Configure cada aplicación para solicitar solo los ámbitos de autorización mínimos necesarios para su funcionalidad.
• Durante la revisión del código, compruebe que la configuración de ámbito y permisos se alinee con los requisitos de seguridad y no conceda acceso innecesario.
• Aplique la revisión del mismo nivel para todo el código de la aplicación antes de realizar la implementación en entornos de producción.
• Asegúrese de que el código de la aplicación registra registros de auditoría estructurados para cada acción realizada en nombre de los usuarios, incluida la identidad del usuario, el tipo de acción, el recurso de destino y el estado.

Métodos de autenticación

Para obtener tokens para Aplicaciones de Databricks, los usuarios y las entidades de servicio se autentican mediante flujos estándar de OAuth 2.0. El método depende de si el autor de la llamada es un usuario o una carga de trabajo automatizada.

Para el inicio de sesión del área de trabajo (solo usuarios):

• Inicio de sesión único (SSO): Los usuarios se autentican a través del proveedor de identidades cuando se configura el inicio de sesión único (SSO).
• Contraseña única (OTP): Los usuarios reciben una contraseña temporal si el inicio de sesión único no está configurado.

Para flujos de OAuth (aplicaciones y cargas de trabajo):

• OAuth de usuario a máquina (U2M): Los usuarios se autentican y los tokens resultantes habilitan la autorización de usuario para que la aplicación pueda actuar en nombre del usuario.
• OAuth de máquina a máquina (M2M): Las entidades de servicio se autentican mediante credenciales de cliente o federación. Estos tokens respaldan la autorización de la aplicación, donde la aplicación actúa como sí misma en lugar de un usuario.

Para obtener instrucciones para llamar a una aplicación de Databricks mediante la autenticación de tokens, consulte Conexión a una aplicación de Databricks de API mediante la autenticación de tokens.

Comparación y combinación de modelos

Las aplicaciones de Databricks pueden usar la autorización de aplicaciones y usuarios de forma independiente o conjunta. Estos modelos sirven para diferentes propósitos y están diseñados para funcionar en paralelo.

Modelo de autorización	Cuándo usar	Ejemplos de casos de uso
Autorización de la aplicación	Cuando la aplicación realiza operaciones que no dependen de la identidad del usuario	Escritura de registros, acceso a la configuración compartida, llamada a servicios externos
Autorización de usuario	Cuando la aplicación necesita acceder a los recursos en el contexto del usuario actual	Consulta de datos del catálogo de Unity, inicio del proceso, aplicación de permisos de nivel de fila
Ambos	Cuando la aplicación realiza operaciones compartidas y específicas del usuario	Registro de métricas con identidad de aplicación, consulta de datos filtrados con identidad de usuario