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.

Esses modelos oferecem aos desenvolvedores um controle detalhado sobre o que o aplicativo pode acessar e quais permissões ele usa. Por exemplo, um aplicativo pode usar a autorização de aplicativo para gravar logs ou ler a configuração compartilhada. Em seguida, ele pode aproveitar a autorização do usuário para consultar dados com as permissões do usuário, que o Unity Catalog aplica por meio de políticas como filtragem em nível de linha ou coluna.

Autorização do aplicativo

Cada aplicativo Databricks tem uma entidade de serviço dedicada que atua como sua identidade quando acessa o recurso Databricks. Essa entidade de serviço é exclusiva da instância do aplicativo e não pode ser reutilizada entre aplicativos. 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 os recursos explicitamente concedidos a ele, mesmo fora do contexto da 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 uma ID exclusiva. O senhor pode copiá-lo da Autorização do aplicativo tab:

Quando o senhor cria um aplicativo, a 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:

• 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 usam as permissões da entidade de serviço. O senhor pode conceder à 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.

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.

Escolha um modelo de autorização

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.

Use a autorização de aplicativo quando o aplicativo realizar operações que não dependam da identidade do usuário. Isso inclui escrever logs, acessar a configuração compartilhada ou chamar um serviço externo.

Use a autorização do usuário quando o aplicativo precisar acessar o recurso no contexto do usuário, como consultar dados regidos por Unity Catalog ou iniciar compute em nome do usuário.

Muitos aplicativos combinam os dois modelos. Por exemplo, um aplicativo pode usar sua entidade de serviço para gravar métricas de uso em uma tabela de registro e, ao mesmo tempo, aproveitar a autorização do usuário para executar SQL consultas que retornam resultados específicos do usuário com base em controles de acesso no nível da linha.

Implemente autorização em aplicativos

Para usar a autorização do aplicativo ou do usuário em Databricks Apps, configure a identidade apropriada e passe as credenciais corretas quando fizer solicitações ao serviço Databricks.

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

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

Exemplo: consulta com autorização de aplicativo

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

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

from fastapi import Request
import gradio as gr

request: Request = gr.Request().get("request")
user_access_token = dict(request.headers).get('X-Forwarded-Access-Token')

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

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

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

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. Isso reduz o risco de exposição de dados devido a uma lógica de permissão obsoleta ou desalinhada.

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 controlar o que o aplicativo pode fazer em nome do usuário. Os escopos restringem o acesso a tipos específicos de APIs ou de recurso, como:

• sql para consultar o armazém SQL
• serving.serving-endpoints servindo modelo
• vectorsearch.vector-search-endpoints para pesquisa vetorial

Se o senhor não selecionar nenhum escopo, o site Databricks atribui um conjunto default 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 aos dados ou ao recurso compute. Você pode adicionar 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 somente os escopos necessários. A 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 servindo modelo, mesmo que o usuário possa fazê-lo 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. Opcionalmente, os administradores podem conceder consentimento em nome dos usuários para alinhar o acesso às políticas organizacionais.

Configure a autorização do usuário em seu 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.

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

Na etapa Configure (Configurar ), clique em +Add scope (Adicionar escopo ) e selecione os escopos que definem quais Databricks APIs ou recurso o aplicativo pode acessar em nome do usuário. A Databricks impõe esses escopos em tempo de execução e exige o consentimento do usuário ou do 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.