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 . Esta entidade de serviço é exclusiva da instância do aplicativo e não pode ser reutilizada entre aplicativos. Não é possível alterar a entidade de serviço atribuída a um aplicativo ou especificar uma entidade de serviço existente durante a criação do aplicativo. 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 dá suporte a cenários como processamento em segundo plano ou tarefa automatizada.

A entidade de serviço é representada por um ID único. Copie-o da tab Autorização do aplicativo:

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 utilizam as permissões da entidade de serviço. Conceda à 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.

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

Os aplicativos que utilizam autorização de usuário devem declarar escopos de autorização específicos para limitar 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 o armazém SQL
• dashboards.genie para gerenciar seu Espaço Genie
• files.files para gerenciar seus arquivos e diretórios

Se você não selecionar nenhum escopo, Databricks atribuirá um conjunto default que permite ao aplicativo recuperar 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 acesso a dados ou recursos compute . Adicione 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 apenas os escopos necessários. O 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 do modelo de servir, mesmo que o usuário possa 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. Após conceder o consentimento, os usuários não podem revogá-lo. Os administradores podem, opcionalmente, conceder consentimento em nome dos usuários para alinhar o acesso às políticas da organização.

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.

Configure a autorização do usuário ao criar ou editar um aplicativo na interface do usuário do Databricks.

Em Autorização do usuário , clique em +Adicionar escopo e selecione os escopos que definem quais APIs ou recursos Databricks o aplicativo pode acessar em nome do usuário. O Databricks impõe esses escopos em tempo de execução e exige o consentimento do usuário ou 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.

Restringir os escopos de autorização do usuário

Os administradores do espaço de trabalho podem controlar quais escopos OAuth os desenvolvedores de aplicativos têm permissão para adicionar aos aplicativos no workspace.

1. Clique no seu nome de usuário na barra superior do workspace do Databricks e selecione Configurações .
2. Clique em Desenvolvimento .
3. Em Aplicativos , encontre a configuração Restringir escopos OAuth para aplicativos aos valores selecionados e configure a lista de permissões.
4. Atualize a página para que a alteração entre em vigor.

O valor default é Todas APIs , que permite todos os escopos suportados. Selecionar "Nenhum" desativa a autorização do usuário.

Os administradores da conta podem adicionar escopos aos aplicativos, mesmo que esses escopos não estejam na lista de permissões workspace .

nota

Os aplicativos que já estão em execução continuarão a ser executados com seus escopos existentes. Você não pode iniciar, implantar ou atualizar um aplicativo até remover os escopos não permitidos.

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.

Métodos de autenticação

Para obter tokens para aplicativos Databricks , tanto os usuários quanto a entidade de serviço se autenticam usando fluxos OAuth 2.0 padrão. O método depende se quem faz a chamada é um usuário ou uma carga de trabalho automatizada.

Para login workspace (somente usuários):

• Logon único (SSO): os usuários são autenticados por meio do seu provedor de identidade quando o logon único (SSO) está configurado.
• Senha de uso único (OTP): os usuários recebem uma senha temporária se o SSO não estiver configurado.

Para fluxos OAuth (aplicativos e cargas de trabalho):

• OAuth de usuário para máquina (U2M): os usuários se autenticam e os tokens resultantes permitem a autorização do usuário para que o aplicativo possa agir em nome do usuário.
• Machine-to-machine (M2M) OAuth: entidade de serviço que autentica usando credenciais de cliente ou federação. Esses tokens sustentam a autorização do aplicativo, onde o aplicativo atua como ele mesmo e não como um usuário.

Para obter instruções sobre como chamar um aplicativo Databricks usando autenticação por tokens, consulte Conectar-se a um aplicativo Databricks API usando autenticação por tokens.

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