Configurar a autorização em um aplicativo Databricks

O Databricks Apps oferece suporte ao desenvolvimento seguro de aplicativos no Databricks. À medida que os aplicativos acessam dados e serviços em workspace, eles devem usar mecanismos de autenticação e autorização que imponham controles de acesso a dados e respeitem as permissões do usuário. O modelo de autorização do Databricks Apps é baseado no OAuth 2.0 e combina as permissões atribuídas ao aplicativo com as do usuário que o acessa.

Para dar suporte a essa estrutura, o Databricks Apps usa dois modelos de identidade complementares:

• A autorização do aplicativo dá ao aplicativo sua própria identidade com um conjunto consistente de permissões.
• A autorização do usuário permite que o aplicativo use a identidade e as permissões do usuário que está interagindo com ele.

Autorização do aplicativo

Cada aplicativo Databricks tem uma entidade de serviço dedicada que atua como sua identidade quando acessa o recurso Databricks. Essa entidade de serviço é exclusiva da instância do aplicativo e não pode ser reutilizada entre aplicativos. Databricks usa essa identidade para avaliar as permissões do aplicativo independentemente de qualquer usuário, o que garante que o aplicativo só possa acessar os recursos explicitamente concedidos a ele, mesmo fora do contexto da interação do usuário.

Essa separação ajuda a impor limites de segurança, o que permite a auditoria da atividade do aplicativo e dá suporte a cenários como processamento em segundo plano ou tarefa automatizada.

A entidade de serviço é representada por uma ID exclusiva. O senhor pode copiá-lo da Autorização do aplicativo tab:

Quando o senhor cria um aplicativo, o Databricks provisiona automaticamente uma entidade de serviço dedicada para o aplicativo. A entidade de serviço permanece a mesma em todas as implementações do aplicativo. Quando o senhor exclui o aplicativo, a Databricks exclui a entidade de serviço.

Use a entidade de serviço para ações que o aplicativo executa por conta própria, sem exigir o contexto de um usuário individual. Os casos de uso comuns incluem:

• Executar tarefa em segundo plano
• Lendo ou gravando configurações ou metadados compartilhados
• Registro de atividade ou métricas de uso
• Chamada de serviço externo por meio de endpoint seguro

Todas as ações iniciadas pelo aplicativo usam as permissões da entidade de serviço. O senhor pode conceder à entidade de serviço acesso a um recurso específico usando atribuições de permissão padrão. No entanto, ele não oferece suporte ao controle de acesso em nível de usuário. Todos os usuários que interagem com o aplicativo compartilham as mesmas permissões definidas para a entidade de serviço, o que impede que o aplicativo aplique políticas refinadas com base na identidade individual do usuário.

O exemplo a seguir mostra como um aplicativo usa sua entidade de serviço para consultar dados em Unity Catalog:

Nesse caso, a entidade de serviço precisa de acesso explícito à tabela SQL warehouse e Unity Catalog que ela consulta.

Esse modelo funciona bem quando se deseja que todos os usuários do aplicativo vejam os mesmos dados ou quando o aplicativo executa operações compartilhadas não vinculadas a controles de acesso específicos do usuário.

Recuperar credenciais de autorização do aplicativo

Para autorização de aplicativos, o site Databricks injeta automaticamente credenciais de entidade de serviço no ambiente do aplicativo. As seguintes variáveis de ambiente contêm os valores necessários do cliente OAuth:

Variável	Descrição
DATABRICKS_CLIENT_ID	entidade de serviço OAuth ID do cliente
DATABRICKS_CLIENT_SECRET	Segredo do cliente OAuth da entidade de serviço

Databricks define a variável de ambiente automaticamente no tempo de execução do aplicativo. O aplicativo usa essas variáveis quando se autentica como ele mesmo.

Python

Python

import os

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

JavaScript

JavaScript

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

nota

Se o senhor estiver usando os SDKs do Databricks, normalmente não precisará acessar manualmente essas variáveis de ambiente. Os SDKs seguem a autenticação unificada e detectam automaticamente as credenciais no ambiente.

Exemplo: consulta com autorização de aplicativo

Python

Este exemplo usa o objeto SDK Config, que extrai as credenciais da entidade de serviço da variável de ambiente e executa a autorização OAuth.

Python

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

Este exemplo usa a variável de ambiente para se autenticar em uma entidade de serviço usando OAuth e executar uma consulta com o driverDatabricks SQL para Node.js.

JavaScript

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

Autorização do usuário

info

Visualização

A autorização do usuário está na Pré-visualização pública.

A autorização de usuário, às vezes chamada de autorização em nome do usuário , permite que um aplicativo Databricks Apps atue com a identidade do usuário do aplicativo. Databricks encaminha os tokens de acesso do usuário para o aplicativo, que usa os tokens para acessar o recurso em nome do usuário. A Databricks aplica todas as permissões com base nas políticas existentes do Unity Catalog do usuário.

Para gerenciar os riscos de segurança dos aplicativos que agem em nome de um usuário, a Databricks usa escopos para limitar as ações que um aplicativo pode executar por meio da autorização do usuário.

Aplique a autorização do usuário quando o aplicativo precisar respeitar as permissões individuais do usuário. Os casos de uso típicos incluem:

• Consultando tabelas ou volumes
• Acessando o site SQL warehouse ou compute
• Trabalho em execução ou fluxo de trabalho vinculado a ações do usuário

Todas as ações usam as permissões existentes do usuário no Unity Catalog:

A autorização de usuário permite o controle de acesso refinado aplicando Unity Catalog recurso como filtros em nível de linha e máscaras de coluna à atividade do aplicativo. Essa abordagem mantém o controle de acesso consistente com a governança do workspace e evita a codificação da lógica de permissão no aplicativo.

Permissões refinadas com autorização do usuário

Quando você adiciona autorização de usuário a um aplicativo, ele aplica as permissões existentes do Unity Catalog do usuário, incluindo:

• Filtros em nível de linha para restringir linhas visíveis
• Máscaras de coluna para editar ou transformar dados confidenciais

Como a Databricks avalia as solicitações de autorização do usuário com a identidade do usuário, essas políticas são aplicadas automaticamente quando o aplicativo acessa os dados. Por exemplo, se uma tabela incluir um filtro de linha que limita a visibilidade por região, o aplicativo retornará somente as linhas que o usuário tem permissão para consultar. Nenhuma lógica de filtragem adicional é necessária no aplicativo.

Essa abordagem evita a duplicação da lógica de controle de acesso no código do aplicativo e garante a consistência com a governança no nível workspace. Quando os administradores atualizam as políticas do Unity Catalog, o aplicativo respeita automaticamente essas alterações. Isso reduz o risco de exposição de dados devido a uma lógica de permissão obsoleta ou desalinhada.

Segurança baseada em escopo e escalonamento de privilégios

Os aplicativos que usam a autorização do usuário devem declarar escopos de autorização específicos para controlar o que o aplicativo pode fazer em nome do usuário. Os escopos restringem o acesso a tipos específicos de APIs ou de recurso, como:

• sql para consultar o armazém SQL
• dashboards.genie para gerenciar seu espaço no Genie
• files.files para gerenciar seus arquivos e diretórios

Se o senhor não selecionar nenhum escopo, o site Databricks atribui um conjunto default que permite que o aplicativo recupere informações básicas de identidade do usuário:

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

Esses padrões são necessários para dar suporte à funcionalidade de autorização do usuário, mas não permitem o acesso aos dados ou ao recurso compute. Você pode adicionar escopos adicionais ao criar ou editar o aplicativo.

Os escopos reforçam o princípio do menor privilégio. Certifique-se de configurar o aplicativo para solicitar somente os escopos necessários. A Databricks bloqueia o acesso a qualquer funcionalidade fora dos escopos aprovados, mesmo que o usuário tenha permissão. Por exemplo, se o aplicativo solicitar apenas o escopo sql, ele não poderá acessar o endpoint servindo modelo, mesmo que o usuário possa fazê-lo fora do aplicativo.

Quando um usuário acessa um aplicativo pela primeira vez, o Databricks solicita que ele autorize explicitamente o aplicativo a agir dentro dos escopos solicitados. Opcionalmente, os administradores podem conceder consentimento em nome dos usuários para alinhar o acesso às políticas organizacionais.

Adicionar escopos a um aplicativo

info

Visualização

A autorização do usuário está na Pré-visualização pública. O administrador do workspace deve habilitá-lo antes que o senhor possa adicionar escopos ao seu aplicativo.

Depois de ativar a autorização do usuário, você deve reiniciar os aplicativos existentes antes de poder adicionar escopos a eles. Se o senhor desativar a autorização do usuário, deverá reiniciar os aplicativos existentes para que eles parem de usar o access token do usuário atual para acessar o recurso.

O senhor pode configurar a autorização do usuário ao criar ou editar um aplicativo na interface do usuário do Databricks.

Na etapa Configure (Configurar ), clique em +Add scope (Adicionar escopo ) e selecione os escopos que definem quais Databricks APIs ou recurso o aplicativo pode acessar em nome do usuário. A Databricks impõe esses escopos em tempo de execução e exige o consentimento do usuário ou do administrador antes de conceder acesso.

Para obter um exemplo completo, consulte a demonstração de autorização do Databricks Apps no GitHub. O aplicativo de exemplo mostra como usar os modelos de autorização do aplicativo e do usuário e inclui instruções de configuração e exemplos de consultas com autorização do usuário.

Recuperar credenciais de autorização do usuário

Para autorização do usuário, o site Databricks encaminha a identidade do usuário e os tokens de acesso ao aplicativo em cabeçalhos HTTP. O aplicativo precisa extrair esses cabeçalhos para agir em nome do usuário.

A forma como você recupera esses cabeçalhos depende da estrutura que você usa.

Streamlit

Python

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

Gradio

Python

import gradio as gr

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

O Gradio injeta automaticamente o objeto de solicitação na função do seu aplicativo se você o declarar como um parâmetro. Você não precisa criar ou buscar a solicitação manualmente.

Dash and Flask

Python

from flask import request

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

Shiny

Python

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

Express

JavaScript

import express from 'express';

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

Exemplo: Consulta com autorização do usuário

Nesse caso, o aplicativo passa os tokens de acesso do usuário diretamente para o conector e o site Databricks aplica as permissões do usuário à consulta.

Python

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

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

Práticas recomendadas para autorização de usuários

Ao criar aplicativos que realizam ações em nome dos usuários, siga estas práticas recomendadas para garantir acesso seguro e auditável:

• Armazene o código do aplicativo em pastas acessíveis somente ao proprietário do aplicativo ou a um pequeno conjunto de usuários confiáveis.
• Conceda permissões CAN MANAGE somente a desenvolvedores seniores confiáveis que sejam responsáveis pela manutenção e análise do aplicativo. Conceda as permissões do CAN USE somente a usuários ou grupos específicos aprovados para executar o aplicativo.
• Certifique-se de que tokens não seja impresso, registrado ou gravado em arquivos. Isso se aplica a todas as instruções de registro, ferramentas de depuração e manipuladores de erros. Por exemplo, em vez de print(f"User token: {token}"), use headers = {"Authorization": f"Bearer {token}"}.
• Configure cada aplicativo para solicitar somente os escopos mínimos de autorização necessários para sua funcionalidade.
• Durante a revisão do código, verifique se as configurações de escopo e permissão estão alinhadas aos requisitos de segurança e não concedem acesso desnecessário.
• Impor a revisão por pares para todos os códigos de aplicativos antes de implantá-los em ambientes de produção.
• Certifique-se de que o código do seu aplicativo registre logs de auditoria estruturados para cada ação executada em nome dos usuários, incluindo a identidade do usuário, o tipo de ação, o recurso de destino e o status.

Compare e combine modelos

Os aplicativos Databricks podem usar a autorização do aplicativo e do usuário de forma independente ou em conjunto. Esses modelos têm finalidades diferentes e são projetados para funcionar em paralelo.

Modelo de autorização	Quando usar	Exemplos de casos de uso
Autorização do aplicativo	Quando o aplicativo realiza operações que não dependem da identidade do usuário	Escrever logs, acessar a configuração compartilhada, chamar o serviço externo
Autorização do usuário	Quando o aplicativo precisa acessar o recurso no contexto do usuário atual	Consultar dados do site Unity Catalog, iniciar o site compute, aplicar permissões em nível de linha
Ambos (combinados)	Quando o aplicativo executa operações compartilhadas e específicas do usuário	Registro de métricas com a identidade do aplicativo, consulta de dados filtrados com a identidade do usuário