Configurar a autorização em um aplicativo Databricks

O Databricks Apps dá suporte ao desenvolvimento seguro de aplicativos no Azure Databricks. Como os aplicativos acessam dados e serviços em um espaço de trabalho, 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 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 interage com ele.

Autorização do aplicativo

Cada aplicação do Azure Databricks tem uma entidade de serviço dedicada que atua como a sua identidade quando acede aos recursos do Azure Databricks. Este principal de serviço é exclusivo para a instância da aplicação e não pode ser reutilizado entre aplicações. O Azure 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 recursos explicitamente concedidos a ele, mesmo fora do contexto de 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 oferece suporte a cenários como processamento em segundo plano ou tarefas automatizadas.

A entidade de serviço é representada por um ID exclusivo. Você pode copiá-lo da guia Autorização do aplicativo:

Quando você cria um aplicativo, o Azure Databricks cria automaticamente uma entidade de serviço dedicada e a atribui ao aplicativo. 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:

• Executando tarefas em segundo plano
• Leitura ou gravação de metadados ou configurações compartilhadas
• Registrando a atividade ou as métricas de uso
• Chamar serviços externos através de terminais seguros

Todas as ações iniciadas pelo aplicativo usam as permissões da entidade de serviço. Você pode conceder ao principal de serviço acesso a recursos específicos usando atribuições de permissão padrão. No entanto, ele não suporta controle de acesso no nível do 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 no Unity Catalog:

Nesse caso, o principal de serviço precisa de acesso explícito ao armazém de dados SQL e à tabela do Unity Catalog que consulta.

Esse modelo funciona bem quando você 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 de aplicativo

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

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

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

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;

Observação

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

Exemplo: Consulta com autorização de aplicativo

Python

Este exemplo usa o objeto SDK Config, que extrai as credenciais do serviço principal de variáveis de ambiente e realiza a autorização 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

Este exemplo usa variáveis de ambiente para autenticar com uma entidade de serviço usando OAuth e executar uma consulta com o 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();

Autorização de utilizador

Importante

A autorização do usuário está em Visualização pública.

A autorização do usuário, às vezes chamada de autorização em nome do usuário, permite que um aplicativo Databricks Apps aja com a identidade do usuário do aplicativo. O Azure Databricks encaminha o token de acesso do usuário para o aplicativo, que usa o token para acessar recursos em nome do usuário. O Azure Databricks impõe todas as permissões com base nas políticas existentes do Catálogo Unity do usuário.

Para gerenciar os riscos de segurança de aplicativos que atuam em nome de um usuário, o Azure Databricks usa escopos para limitar quais ações 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
• Acesso a armazéns SQL ou serviços de computação
• Executando trabalhos ou fluxos de trabalho vinculados a ações do usuário

Todas as ações usam as permissões existentes do Catálogo Unity do usuário:

A autorização do usuário permite um controle de acesso refinado aplicando recursos do Catálogo Unity, como filtros de 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 espaço de trabalho e evita codificar a lógica de permissões no aplicativo.

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

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

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

Como o Azure Databricks avalia as solicitações de autorização do usuário com a identidade do usuário, essas políticas se aplicam automaticamente quando o aplicativo acessa dados. Por exemplo, se uma tabela incluir um filtro de linha que limite a visibilidade por região, o aplicativo retornará apenas 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 do espaço de trabalho. Quando os administradores atualizam as políticas do Catálogo Unity, o aplicativo respeita automaticamente essas alterações. Isso reduz o risco de exposição de dados devido a lógica de permissões obsoleta ou desalinhada.

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

Os aplicativos que usam autorização de 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 APIs ou tipos de recursos específicos, como:

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

Se você não selecionar nenhum escopo, o Azure Databricks atribuirá um conjunto padrão 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 a dados ou recursos de computação. Você pode adicionar escopos adicionais ao criar ou editar o aplicativo.

Os âmbitos impõem o princípio do menor privilégio. Certifique-se de configurar o aplicativo para solicitar apenas os escopos necessários. O Azure Databricks bloqueia o acesso a qualquer funcionalidade fora dos escopos aprovados, mesmo que o usuário tenha permissão. Por exemplo, se a aplicação solicitar apenas o sql escopo, não poderá aceder aos endpoints de serviço de modelos, mesmo que o utilizador o possa fazer fora da aplicação.

Quando um usuário acessa um aplicativo pela primeira vez, o Azure 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 com as políticas organizacionais.

Adicionar escopos a uma aplicação

Importante

A autorização do usuário está em Visualização pública. O administrador do espaço de trabalho deve habilitá-lo antes que você possa adicionar escopos ao seu aplicativo.

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

Na etapa Configurar , clique em +Adicionar escopo e selecione os escopos que definem quais APIs ou recursos do Azure Databricks o aplicativo pode acessar em nome do usuário. O Azure Databricks impõe esses escopos em tempo de execução e requer o consentimento do usuário ou administrador antes de conceder acesso.

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

Recuperar credenciais de autorização do usuário

Para autorização do usuário, o Azure Databricks encaminha a identidade do usuário e o token de acesso para o aplicativo em cabeçalhos HTTP. O aplicativo deve extrair esses cabeçalhos para agir em nome do usuário.

Como você recupera esses cabeçalhos depende da estrutura que você usa.

Iluminado em fluxo

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 injeta automaticamente o objeto request na função da sua aplicação, caso este seja declarado como um parâmetro. Você não precisa construir ou buscar a solicitação manualmente.

Dash e Flask

from flask import request

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

Brilhante

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

Expresso

import express from 'express';

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

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

Nesse caso, o aplicativo passa o token de acesso do usuário diretamente para o conector e o Azure Databricks aplica as permissões do usuário à 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,
    accessToken: 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ário

Ao criar aplicativos que executam 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 apenas ao proprietário do aplicativo ou a um pequeno conjunto de usuários confiáveis.
• Conceda CAN MANAGE permissões apenas a desenvolvedores seniores confiáveis que são responsáveis pela manutenção e revisão do aplicativo. Conceda CAN USE permissões apenas a usuários ou grupos específicos aprovados para executar o aplicativo.
• Certifique-se de que os tokens não sejam impressos, registrados ou gravados em arquivos. Isso aplica-se a todas as declarações de registo, ferramentas de depuração e gestores de erros. Por exemplo, em vez de print(f"User token: {token}") usar headers = {"Authorization": f"Bearer {token}"}.
• Configure cada aplicativo para solicitar apenas os escopos de autorização mínimos necessários para sua funcionalidade.
• Durante a revisão de código, verifique se as configurações de escopo e permissão estão alinhadas com os requisitos de segurança e não concedem acesso desnecessário.
• Imponha a revisão por pares para todo o código do aplicativo antes de implantar em ambientes de produção.
• Certifique-se de que o código do 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.

Comparar e combinar modelos

Os aplicativos Databricks podem usar a autorização do aplicativo e do usuário de forma independente ou em conjunto. Estes modelos servem diferentes finalidades e são concebidos para funcionar em paralelo.

Modelo de autorização	Quando utilizar	Exemplos de casos de uso
Autorização do aplicativo	Quando o aplicativo executa operações que não dependem da identidade do usuário	Escrever logs, aceder à configuração partilhada, chamar serviços externos
Autorização do utilizador	Quando o aplicativo precisa acessar recursos no contexto do usuário atual	Consultando dados do Catálogo Unity, iniciando computação, impondo permissões em nível de linha
Ambos (combinados)	Quando o aplicativo executa operações compartilhadas e específicas do usuário	Registrando métricas com identidade do aplicativo, consultando dados filtrados com identidade do usuário