Configurar a autorização em um aplicativo Databricks

O Databricks Apps suporta o desenvolvimento seguro de aplicações 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 Azure Databricks tem um principal de serviço dedicado que atua como a sua identidade quando acede aos recursos do Azure Databricks. O principal de serviço é exclusivo para a instância da aplicação e não pode ser reutilizado em várias aplicações. 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. O Azure Databricks utiliza esta identidade para avaliar as permissões da aplicação independentemente de qualquer utilizador, garantindo que a aplicação só pode aceder aos recursos explicitamente concedidos, mesmo fora do contexto da interação com o utilizador.

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. Copie-o da guia Autorização do aplicativo:

Quando cria uma aplicação, o Azure Databricks fornece automaticamente um principal de serviço dedicado para a aplicação. A entidade de serviço permanece a mesma em todas as implantações do aplicativo. Quando apagas a aplicação, o Azure Databricks elimina o principal do 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:

• 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. Conceda à entidade 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 a autorização da aplicação, o Azure Databricks injeta automaticamente as credenciais de entidade de serviço no ambiente da aplicação. As seguintes variáveis de ambiente contêm os valores de cliente OAuth necessários:

O Azure Databricks define automaticamente as variáveis de ambiente no runtime da aplicação. 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 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 do utilizador

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 utilizador para a aplicação, que utiliza o token para aceder aos recursos em nome do utilizador. Azure Databricks aplica todas as permissões com base nas políticas existentes do utilizador Unity Catalog.

Para gerir os riscos de segurança das aplicações que atuam em nome do utilizador, o Azure Databricks utiliza escopos para limitar as ações que uma aplicação pode realizar através da autorização do utilizador.

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 pedidos de autorização do utilizador com a identidade do utilizador, estas políticas aplicam-se automaticamente quando a aplicação acede aos 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.

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

As aplicações que utilizam autorização de utilizador devem declarar escopos de autorização específicos para limitar o que a aplicação pode fazer em nome do utilizador. 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 não selecionar nenhum escopo, o Azure Databricks atribui um conjunto padrão que permite à aplicação recuperar informações básicas de identidade do utilizador:

• 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. Adicione 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 âmbitos aprovados, mesmo que o utilizador tenha permissão. Por exemplo, se a app pedir apenas o escopo sql, não pode aceder aos endpoints de serviço de modelos, mesmo que o utilizador pudesse fora da app.

Quando um utilizador acede pela primeira vez a uma aplicação, o Azure Databricks solicita-lhe que autorize explicitamente a aplicação a agir dentro dos escopos solicitados. Depois de conceder o consentimento, os utilizadores não podem revogá-lo. 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

Configure a autorização do utilizador quando criar ou editar uma aplicação na interface do Azure Databricks.

Em Autorização de utilizador, clique em +Adicionar âmbito e selecione os âmbitos que definem quais Azure Databricks APIs ou recursos a aplicação pode aceder em nome do utilizador. O Azure Databricks aplica estes escopos em tempo de execução e requer consentimento do utilizador ou administrador antes de conceder o acesso.

Para um exemplo completo, veja a demonstração de autorização das aplicações 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 a autorização do utilizador, Azure Databricks encaminha a identidade e o token de acesso do utilizador para a aplicação 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.

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

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

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: Consulta com autorização de usuário

Neste caso, a aplicação passa o token de acesso do utilizador diretamente para o conector, e o Azure Databricks aplica as permissões do utilizador à 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 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.

Métodos de autenticação

Para obter tokens para aplicativos Databricks, os usuários e as entidades de serviço são autenticados usando fluxos OAuth 2.0 padrão. O método depende se o chamador é um usuário ou uma carga de trabalho automatizada.

Para login no espaço de trabalho (somente usuários):

• Logon único (SSO): Os usuários se autenticam por meio de seu provedor de identidade quando o logon único (SSO) é 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 habilitam a autorização do usuário para que o aplicativo possa agir em nome do usuário.
• OAuth 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, onde o aplicativo age como ele mesmo em vez de um usuário.

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

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.