Configurar a autorização em um aplicativo Databricks

O modelo de autorização do Databricks Apps é baseado em OAuth 2.0 e combina as permissões atribuídas ao aplicativo com as do usuário que o acessa. Como os aplicativos acessam dados e serviços dentro de um workspace, eles devem usar autenticação e autorização que apliquem controles de acesso a dados e respeitem as permissões do usuário.

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 um service principal dedicado que atua como sua identidade ao acessar recursos do Databricks. Este service principal é exclusivo da instância do aplicativo e não pode ser reutilizado em outros aplicativos. Você não pode alterar o service principal atribuído a um aplicativo nem especificar um service principal existente durante a criação do aplicativo. O Databricks usa essa identidade para avaliar as permissões do aplicativo independentemente de qualquer usuário, para que o aplicativo possa acessar apenas os recursos explicitamente concedidos a ele, mesmo fora do contexto de interação do usuário.

Essa separação impõe limites de segurança entre os aplicativos. Isso também torna a atividade do aplicativo auditável e oferece suporte a cenários como processamento em segundo plano ou tarefas automatizadas.

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

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

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 granulares 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
• genie para gerenciar seu Genie Agent
• 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 conceda ao aplicativo permissão para agir dentro de cada escopo solicitado. 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 organizacionais.

Adicionar escopos a um aplicativo

Adicione escopos de autorização na interface do usuário do Databricks ou com a CLI do Databricks.

UI

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.

CLI

Passe user_api_scopes ao criar ou atualizar um aplicativo:

Bash

databricks apps create <app-name> \
  --json '{
    "user_api_scopes": ["sql", "files"]
  }'

Bash

databricks apps create-update <app-name> \
  --json '{
    "update_mask": "user_api_scopes",
    "app": {
      "user_api_scopes": ["sql", "files"]
    }
  }'

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.

Escopos compatíveis

O Databricks Apps oferece suporte aos seguintes escopos da API do Databricks:

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (executar queries SQL somente de leitura)

O Databricks Apps também é compatível com os seguintes escopos de SDK. Esses escopos podem usar o modificador :read para restringir o acesso a Endpoint GET.

• catalog.catalogs
• catalog.connections
• catalog.schemas
• catalog.tables
• workspace.workspace

Os seguintes escopos estão obsoletos. Use o escopo atual em vez disso.

Escopo obsoleto	Escopo atual
dashboards.genie	genie
files.files	files
serving.serving-endpoints	model-serving
serving.serving-endpoints-data-plane	model-serving
sql.alerts	sql
sql.alerts-legacy	sql
sql.dashboards	sql
sql.data-sources	sql
sql.dbsql-permissions	sql
sql.queries	sql
sql.queries-legacy	sql
sql.query-history	sql
sql.statement-execution	sql
sql.warehouses	sql
vectorsearch.vector-search-endpoints	vector-search
vectorsearch.vector-search-indexes	vector-search

Escopo obsoleto	Escopo atual
dashboards.genie	genie
files.files	files
serving.serving-endpoints	model-serving
serving.serving-endpoints-data-plane	model-serving
sql.alerts	sql
sql.alerts-legacy	sql
sql.dashboards	sql
sql.data-sources	sql
sql.dbsql-permissions	sql
sql.queries	sql
sql.queries-legacy	sql
sql.query-history	sql
sql.statement-execution	sql
sql.warehouses	sql
vectorsearch.vector-search-endpoints	vector-search
vectorsearch.vector-search-indexes	vector-search

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.

UI

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 é All APIs , que permite todos os escopos compatíveis. Selecionar None desativa a autorização do usuário.

CLI

Use a CLI do Databricks para obter ou atualizar a lista de permissões de escopo.

Para obter a configuração atual:

Bash

databricks workspace-settings-v2 get-public-workspace-setting allowedAppsUserApiScopes

Para definir escopos permitidos específicos:

Bash

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["sql", "files"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Para permitir todos os escopos (default):

Bash

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["*"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Para desabilitar a autorização do usuário, defina allowed_scopes como uma matriz vazia ([]).

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: query 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 do usuário

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.
• Não imprima, log, ou grave tokens em arquivos. Isso se aplica a todas as instruções de log, ferramentas de depuração e manipuladores de erro. 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.
• Registre logs de auditoria estruturados para cada ação que seu aplicativo executa 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

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