Um guia prático para usar a autorização em nome do usuário no Databricks Apps para entregar experiências personalizadas de dados e AI que respeitam permissões
por Aakrati Talati, Cynthya Peranandam, Tushar Madan, Evan Pandya e Theo Fernandez
O Databricks Apps permite que desenvolvedores criem e implantem aplicativos de dados e IA diretamente na plataforma Databricks, desde dashboards interativos e ferramentas operacionais até agentes de IA personalizados.
Agora geralmente disponível, a autorização em nome do usuário (OBO) torna possível criar aplicativos que oferecem experiências personalizadas e cientes de permissões, sem a necessidade de reimplementar regras de governança de dados no código do aplicativo. Quando um aplicativo chama APIs do Databricks compatíveis com OBO, ele age usando a identidade do usuário conectado: o Unity Catalog aplica as permissões de dados existentes desse usuário, incluindo filtros de linha e máscaras de coluna, e os escopos de API limitam as operações que o aplicativo pode realizar em nome do usuário. Os aplicativos podem continuar a usar seu service principal dedicado para operações próprias do aplicativo, como ler configurações compartilhadas ou gravar métricas do aplicativo.
Por exemplo, um assistente de insights de vendas pode responder a perguntas usando apenas as contas e os campos que um vendedor está autorizado a acessar, sem conceder ao aplicativo amplos recursos de SQL ou de administração do workspace.
Ao projetar um aplicativo, pergunte-se: De quem são as permissões que devem governar esta operação específica?
O Databricks Apps oferece suporte a dois modelos de autorização complementares: autorização do aplicativo e autorização do usuário. A autorização do aplicativo usa o service principal dedicado do aplicativo e é adequada para operações próprias do aplicativo ou experiências que devem retornar o mesmo resultado para todos os usuários. A autorização do usuário usa a identidade do usuário conectado quando as permissões desse usuário devem governar uma operação. A maioria dos aplicativos de produção pode usar ambos os modelos, escolhendo a identidade apropriada para cada caminho de solicitação. Consulte Configurar autorização em um aplicativo Databricks.
Operação | Identidade de autorização | Escopo | Por quê |
Consultar dados filtrados pelo usuário atual | Autorização do usuário (OBO) | Escopo da API: | A consulta é executada como o usuário e é limitada a consultas SQL somente leitura. |
Ler configurações compartilhadas ou metadados | Autorização do aplicativo | Permissões de identidade do aplicativo | O service principal do aplicativo fornece acesso consistente. |
Executar jobs em segundo plano ou manutenção | Autorização do aplicativo | Permissões de identidade do aplicativo | O trabalho em segundo plano não deve depender de uma sessão de usuário. |
Realizar uma ação acionada pelo usuário em dados governados | Autorização do usuário (OBO) | O escopo da API necessário para essa operação | A ação é avaliada usando as permissões do usuário iniciador. |
Combinar comportamento compartilhado com dados específicos do usuário | Ambos | Escopos de API separados para cada recurso autorizado pelo usuário | Use um cliente de aplicativo para operações próprias do aplicativo e um cliente de usuário para operações governadas. |
Considere um aplicativo que responde a perguntas como: Como está o desempenho das minhas contas neste trimestre e o que explica a mudança? O aplicativo precisa de:

Isso se encaixa perfeitamente na autorização do usuário. O aplicativo passa o token de acesso encaminhado do usuário solicitante para o conector SQL, e o Databricks avalia a consulta usando o warehouse existente desse usuário e as permissões do Unity Catalog. Um gerente regional pode ver apenas as contas de sua região, enquanto um líder nacional vê todas as regiões, sem que o aplicativo precise recriar essas regras no código. Quando os administradores atualizam as políticas do Unity Catalog, as solicitações subsequentes do aplicativo refletem essas alterações.
A permissão do usuário determina quais dados a consulta pode retornar. A próxima decisão de design é o que o aplicativo tem permissão para fazer em nome do usuário com o token de usuário encaminhado.
O assistente de insights de vendas precisa executar consultas somente leitura. Ele não precisa de acesso amplo ao SQL para gerenciar recursos ou realizar outras operações de SQL. Por esse motivo, ele deve solicitar sql:restricted-query em vez do escopo sql mais amplo.
sql:restricted-query permite que o aplicativo execute consultas SQL somente leitura. Ele não permite que o aplicativo realize outras operações de SQL. Isso cria uma correspondência melhor entre o comportamento do produto do aplicativo e seu limite de autorização: o aplicativo pode ler dados governados para análise, mas não pode usar a identidade do usuário como uma credencial operacional ampla de SQL.
Se o aplicativo também invocar o Genie ou o Unity Gateway em nome de um usuário, solicite apenas os escopos correspondentes, como genie ou ai-gateway. Não solicite files, model-serving ou vector-search, a menos que o aplicativo realmente use esses recursos.
Os escopos são um teto de capacidade, não uma concessão de acesso a dados. O aplicativo deve ter o escopo de API apropriado, e o usuário ainda deve ter permissão para acessar o recurso de destino. Consulte Segurança baseada em escopo e escalonamento de privilégios.

Configure a autorização do usuário na UI do Databricks ou em um Declarative Automation Bundle.
Para um assistente de análise somente leitura, o aplicativo pode declarar:
Observação: o escopo da API faz parte da configuração de autorização do usuário declarada do aplicativo. Ele não concede acesso a um SQL warehouse ou a dados do Unity Catalog. O usuário solicitante ainda deve ter permissão para usar o SQL warehouse de destino e ter os privilégios necessários do Unity Catalog nos dados que estão sendo consultados.
Quando um usuário acessa um aplicativo autorizado pelo usuário pela primeira vez, o Databricks solicita que ele consinta com os escopos de API solicitados.

O Databricks encaminha o token de acesso do usuário atual no cabeçalho HTTP x-forwarded-access-token. O aplicativo deve recuperar esse token para a solicitação que precisa de acesso ao contexto do usuário e passá-lo para o conector SQL.
O exemplo a seguir usa o Flask e o Databricks SQL Connector para Python para tornar o fluxo de tokens explícito. Se você criar o aplicativo com o Databricks AppKit, aplique o mesmo princípio de autorização: use o cliente de contexto do usuário ou a identidade de tempo de solicitação para operações específicas do usuário e mantenha as operações próprias do aplicativo na identidade do aplicativo.
Observação: O token encaminhado é de curta duração e por requisição. O aplicativo o lê a cada requisição e nunca o armazena entre requisições ou em uma sessão.
A diferença importante em relação à autorização do aplicativo é que o conector recebe o token de usuário encaminhado por meio do access_token. O escopo de API sql:restricted-query limita o aplicativo à capacidade de SQL somente leitura de que ele precisa, enquanto o Unity Catalog determina quais linhas e colunas esse usuário pode realmente acessar. Consulte Query com autorização de usuário.
Os desenvolvedores especificam de quais escopos de API seus aplicativos precisam. Os administradores do workspace podem controlar quais escopos de API os desenvolvedores têm permissão para adicionar aos aplicativos no workspace.

Essa política permite que as equipes criem experiências de análise e IA somente leitura, ao mesmo tempo que evita que os aplicativos solicitem recursos mais amplos ou não relacionados. Um desenvolvedor de aplicativos não pode expandir a autorização do aplicativo além do limite de escopo de API configurado para o workspace.
Isso oferece às organizações dois níveis de controle:
Os administradores do workspace configuram essa lista de permissões em Configurações > Desenvolvimento > Apps. A configuração padrão inclui todas as APIs compatíveis, pode ser restrita a escopos de API selecionados ou definida como Nenhum para desativar a autorização do usuário. Consulte Restringir escopos de autorização do usuário.
Os administradores de conta podem adicionar escopos mesmo quando esses escopos não estão incluídos na lista de permissões do workspace. Se um administrador remover posteriormente um escopo permitido, os aplicativos que já estiverem em execução com esse escopo poderão continuar funcionando, mas não poderão ser iniciados, implantados ou atualizados até que o escopo não permitido seja removido.
Muitos aplicativos úteis precisam de ambos os modelos de autorização. O assistente de insights de vendas pode usar:
É recomendável tornar esse limite de identidade explícito no código do aplicativo, em vez de criar um cliente genérico e reutilizá-lo em todos os lugares. Dependências, nomes e testes separados ajudam a evitar que uma credencial de aplicativo seja usada para um caminho específico do usuário ou que um token de usuário seja retido para trabalho em segundo plano.
Se uma requisição exigir autorização do usuário e o token encaminhado estiver ausente, falhe de forma segura (fail closed) em vez de alternar silenciosamente para a entidade de serviço (service principal) do aplicativo. Caso contrário, o aplicativo poderá retornar uma resposta que parece válida, mas que foi gerada com permissões diferentes. É por isso que o query_as_user no exemplo acima começa com require_user_token em vez de tratar o cabeçalho ausente de forma embutida (inline).
Agentes personalizados implantados no Databricks Apps podem usar o mesmo modelo. Inicialize o cliente do workspace com escopo de usuário dentro do manipulador invoke ou stream no momento da requisição — não na inicialização do aplicativo — porque o token de usuário encaminhado está disponível apenas durante uma requisição ativa do usuário. Use a autorização do aplicativo para recursos compartilhados e operações em segundo plano. Consulte Autenticação para agentes.
A autorização em nome do usuário oferece personalização e governança por meio do mesmo mecanismo. As permissões do Unity Catalog do usuário decidem quais dados um aplicativo pode acessar, e o escopo de API correspondente mais restrito decide o que ele pode fazer em nome dele. Para começar, confira nossa documentação de ajuda para obter mais recursos e práticas recomendadas.
(Esta publicação no blog foi traduzida utilizando ferramentas baseadas em inteligência artificial) Publicação original
Assine nosso blog e receba os posts mais recentes diretamente na sua caixa de entrada.