Configurar a autorização em um aplicativo do Databricks

O Databricks Apps dá suporte ao desenvolvimento seguro de aplicativos no Azure Databricks. À medida que os aplicativos acessam dados e serviços em um workspace, eles devem usar mecanismos de autenticação e autorização que impõem controles de acesso a dados e respeitam 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 fornece 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 de aplicativo

Cada aplicativo do Azure Databricks tem uma entidade de serviço dedicada que atua como sua identidade quando acessa recursos do Azure Databricks. Essa entidade de serviço é exclusiva da instância do aplicativo e não pode ser reutilizada entre aplicativos. Você não pode 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. 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 concedidos explicitamente 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 tarefas automatizadas.

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

Quando você cria um aplicativo, o Azure Databricks provisiona automaticamente uma entidade de serviço dedicada para o aplicativo. A entidade de serviço permanece a mesma em todas as implantações do aplicativo. Quando você exclui o aplicativo, o Azure 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 precisar do 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ção compartilhada
• Registro de atividade ou métricas de uso
• Chamando serviços externos por meio de interfaces seguras

Todas as ações iniciadas pelo aplicativo usam as permissões da entidade de serviço. Conceda ao principal de serviço acesso a recursos específicos usando atribuições de permissão padrão. No entanto, ele não dá suporte ao 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 imponja políticas refinadas com base na identidade do usuário individual.

O exemplo a seguir mostra como um aplicativo usa sua entidade de serviço para consultar dados no Catálogo do Unity:

Nesse caso, a entidade de serviço precisa de acesso explícito ao SQL Warehouse e à tabela do Catálogo Unity 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 aplicativos, o Azure Databricks injeta automaticamente as credenciais da entidade de serviço no ambiente do aplicativo. As variáveis de ambiente a seguir contêm os valores de cliente OAuth necessários:

O Azure Databricks define as variáveis de ambiente automaticamente no runtime 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;

Exemplo: Consulta com autorização de aplicativo

Python

Este exemplo usa o objeto Config do SDK, que extrai as credenciais da entidade de serviço de variáveis de ambiente e executa 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 um principal de serviço usando OAuth e executar uma consulta com o Driver do SQL do Databricks para 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 do usuário

A autorização do usuário, às vezes conhecida como autorização em nome do usuário, permite que um aplicativo do Databricks Apps atue 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 do 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 de usuário individuais. Casos de uso típicos incluem:

• Consultando tabelas ou volumes
• Acessando warehouses SQL ou 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 do Unity do usuário:

A autorização do usuário permite o controle de acesso refinado aplicando recursos do Catálogo do 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 que a lógica de permissão seja codificada 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 do 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 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 duplicar a lógica de controle de acesso no código do aplicativo e garante a consistência com a governança no nível do workspace. Quando os administradores atualizam as políticas do Catálogo do Unity, o aplicativo respeita automaticamente essas alterações.

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 limitar o que o aplicativo pode fazer em nome do usuário. Escopos restringem o acesso a APIs específicas ou tipos de recursos, como:

• sql para consultar os sql warehouses
• dashboards.genie para administrar 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 acesso a dados ou recursos de computação. Adicione escopos adicionais ao criar ou editar o aplicativo.

Os escopos impõem o princípio do privilégio mínimo. Configure 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 o aplicativo solicitar apenas o escopo sql, ele não poderá acessar os pontos de acesso de modelos veiculados, mesmo que o usuário tenha acesso fora do aplicativo.

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. Os administradores podem, opcionalmente, conceder consentimento em nome dos usuários para alinhar o acesso às políticas organizacionais.

Adicionar escopos a um aplicativo

Configure 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 runtime e requer consentimento de 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 modelos de autorização do aplicativo e do usuário e inclui instruções de instalaçã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.

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

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")
    ...

O Gradio injeta automaticamente o objeto de solicitação na função do aplicativo se você declará-lo como um parâmetro. Não é necessário construir ou recuperar a solicitação manualmente.

Dash e 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')

Expresso

import express from 'express';

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

Exemplo: consultar com autorização do 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,
    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 executam ações em nome dos usuários, siga estas práticas recomendadas para garantir o 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 CAN MANAGE permissões somente a desenvolvedores seniores confiáveis responsáveis pela manutenção e revisão do aplicativo. Conceda CAN USE permissões somente a usuários ou grupos específicos aprovados para executar o aplicativo.
• Verifique se os tokens não são impressos, registrados ou gravados em arquivos. Isso se aplica a todas as declarações de log, ferramentas de depuração e manipuladores 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 mínimos de autorização necessários para sua funcionalidade.
• Durante a revisão de código, verifique se as configurações de escopo e permissão se alinham aos requisitos de segurança e não concedem acesso desnecessário.
• Imponha a revisão de pares para todo o código do aplicativo antes de implantar em ambientes de produção.
• Verifique se o código do aplicativo registra 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 o Databricks Apps, usuários e entidades de serviço se autenticam usando fluxos OAuth 2.0 padrão. O método depende se o chamador é um usuário ou uma carga de trabalho automatizada.

Para logon do workspace (somente usuários):

• Logon único (SSO): Os usuários se autenticam por meio do provedor de identidade quando o SSO (logon único) é configurado.
• Senha única (OTP): Os usuários receberão uma senha temporária se o SSO não estiver configurado.

Para fluxos OAuth (aplicativos e cargas de trabalho):

• OAuth do usuário para o computador (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.
• OAuth de máquina a máquina (M2M): As entidades de serviço são autenticadas usando credenciais de cliente ou federação. Esses tokens sustentam a autorização do aplicativo, em que o aplicativo atua como ele mesmo em vez de um usuário.

Para obter instruções para chamar um aplicativo Databricks usando a autenticação de token, consulte Conectar-se a um aplicativo databricks de API usando a autenticação de token.

Comparar e combinar modelos

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