Agora em GA: Criando Databricks Apps que respeitam permissões com autorização em nome do usuário

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.

Comece com a identidade que governa cada operação

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.

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:

• Consultar dados de vendas e clientes como o usuário solicitante.
• Respeitar as permissões do Unity Catalog, incluindo filtros de nível de linha e máscaras de coluna.
• Retornar análises somente leitura.
• Opcionalmente, chamar um serviço separado para resumir os resultados.
• Evitar modificar dados ou gerenciar recursos de SQL.

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.

Use o escopo de API mais restrito que corresponda à tarefa

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 o aplicativo com um escopo de API explícito

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. 

Passe a identidade do usuário para o conector SQL

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.

Permita que os administradores do workspace definam o limite superior

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:

• O aplicativo declara os escopos de API mínimos necessários para sua funcionalidade.
• O administrador do workspace define os escopos de API máximos disponíveis para os aplicativos nesse workspace.

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.

Mantenha separadas as operações de propriedade do aplicativo e de propriedade do usuário

Muitos aplicativos úteis precisam de ambos os modelos de autorização. O assistente de insights de vendas pode usar:

• Um cliente com escopo de aplicativo para gravar métricas do aplicativo ou ler configurações compartilhadas.
• Um cliente com escopo de usuário com sql:restricted-query para consultar dados do usuário atual.
• Um escopo de API de usuário separado se precisar invocar outro serviço Databricks em nome do usuário.

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

Aplique o mesmo padrão aos agentes

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.
 

Proteja a implementação

• Solicite apenas os escopos de API mínimos necessários.
• Mantenha os clientes de propriedade do aplicativo e autorizados pelo usuário separados no código, nos testes e na vinculação de dependências.
• Nunca exiba na tela, registre em log ou persista tokens de acesso encaminhados.
• Restrinja o gerenciamento de aplicativos a desenvolvedores confiáveis e exija revisão por pares para alterações relacionadas à autorização.
• Use a autorização do aplicativo para operações compartilhadas e em segundo plano, em vez de reter tokens de usuário.
• Teste com usuários cujos acessos ao Unity Catalog sejam diferentes e repita esses testes após alterações de política.

Primeiros passos

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