Além da incorporação: como proteger Dashboards de AI/BI para cada visualizador

O desafio

Incorporar um dashboard de AI/BI do Databricks em um aplicativo voltado para o cliente é relativamente simples: habilite a incorporação, gere um token com escopo no backend e renderize o dashboard com o SDK do cliente. O guia fundamental, Como incorporar dashboards de AI/BI do Databricks em aplicativos voltados para o cliente, explica esse processo de ponta a ponta.

A questão mais difícil é a autorização: depois que um dashboard é incorporado, quais linhas cada visualizador deve ver? Um parceiro deve ver apenas os seus próprios dados, enquanto uma equipe interna deve ver apenas a sua região. Este guia mostra como aplicar essas regras.

Este padrão de referência combina vários recursos do Databricks: __aibi_external_value, filtros de linha e máscaras de coluna do Unity Catalog e grupos sincronizados de um provedor de identidade (IdP). Trata-se de um padrão de design, não de um único recurso a ser ativado.

Um livro de regras, dois caminhos de aplicação

A mesma tabela de permissões governa dois caminhos: dashboards incorporados acessados pelo aplicativo e consultas SQL diretas executadas por usuários do Databricks.

Um cenário concreto

Considere uma empresa que usa um dashboard compartilhado de "Tarefas de Contas a Receber (AR) Abertas" para dados em três regiões: West, East e Central. O dashboard atende a dois públicos.

• Parceiros operacionais externos, como Acme Ops, Bolt Partners e Core Logistics, não têm login do Databricks e acessam o dashboard por meio de um portal white-label. Cada parceiro deve ver apenas a sua própria região, com os e-mails de contato mascarados.
• As equipes internas são os funcionários da empresa, que fazem login no Databricks. O Financeiro precisa de acesso a todas as regiões, enquanto uma equipe de operações regionais vê apenas a sua própria. O acesso deles vem de grupos de provedores de identidade, como Okta ou Entra ID, e não de listas de usuários mantidas manualmente.

Cinco visualizadores compartilham um único conjunto de dados, cada um vendo uma parte diferente: Acme Ops, Bolt Partners, Core Logistics, Financeiro e uma equipe de operações regionais. Os exemplos abaixo focam na Acme e no Financeiro; os identificadores partner_acme, finance_all e West representam esses exemplos. A Acme vê a região West com os e-mails mascarados, enquanto o Financeiro vê as três regiões na íntegra, ambos a partir do mesmo dashboard publicado.

Uma tabela, uma view, um dashboard

As regras de acesso ficam em um único lugar, em vez de ficarem espalhadas por dashboards ou consultas. Um dashboard por cliente cria cópias que podem ficar desatualizadas, enquanto a repetição de filtros em cada consulta cria oportunidades para erros.

O modelo consiste em três objetos:

• A tabela base `open_ar_tasks` contém uma linha por tarefa de AR, marcada com uma região e um e-mail de contato.

• A tabela de permissões é a única fonte de verdade para o acesso. Cada linha identifica a região que um escopo pode acessar e se os valores confidenciais devem ser mascarados. A coluna viewer_scope armazena IDs de parceiros externos, como partner_acme, e nomes de grupos internos, como finance_all.

• A view protegida junta a tabela base à de permissões, de modo que o visualizador veja apenas as regiões permitidas, com os e-mails mascarados quando o sinalizador estiver definido.

Na maioria das implantações, um sistema de permissões upstream ou um mapeamento de grupo para região de propriedade do aplicativo preenche essa tabela; ela não é editada manualmente para cada visualizador.

Isso evita dashboards por cliente e filtros repetidos em várias consultas. As regras residem em uma tabela que pode ser consultada, auditada e alterada sem modificar o dashboard.

Aplicada por visualizador, a view protegida retorna apenas aquilo a que o visualizador tem direito:

Acme (external_value = partner_acme): apenas West, e-mail de contato mascarado.

Financeiro (external_value = finance_all): todas as três regiões, e-mail de contato completo.

De onde vem o __aibi_external_value

O backend define esse valor quando gera o token de incorporação. Ele se autentica como uma entidade de serviço (service principal) e solicita um token com escopo do Databricks com dois valores: external_viewer_id, que identifica o visualizador para fins de auditoria, e external_value, que representa o escopo do visualizador. O Databricks assina o token, e o visualizador não pode modificar o valor incorporado, que é exposto ao SQL do dashboard como __aibi_external_value. Como ele contém as credenciais da entidade de serviço, esse backend é um componente confiável do lado do servidor, nunca o navegador, com essas credenciais mantidas em um gerenciador de segredos (secrets manager) em vez de no controle de origem.

O detalhe fundamental é qual identidade executa a consulta. As consultas incorporadas são executadas sob a identidade de publicação configurada, não sob a identidade do Databricks do visualizador.

Para incorporação externa, o Databricks recomenda permissões de dados individuais e a concessão de acesso aos próprios dados para a entidade de serviço, de modo que as consultas sejam executadas como a entidade de serviço. (Em vez disso, a publicação com permissões de dados compartilhadas executa consultas usando as credenciais do publicador.) A view então restringe esse acesso para cada visualizador por meio do __aibi_external_value. Como a consulta é executada como a entidade de serviço, is_account_group_member() não consegue identificar a pessoa real que está visualizando o dashboard no caminho de incorporação.

O detalhe importante é que o external_value não se limita a um ID de parceiro. Pode ser qualquer escopo que o backend assine no token, por exemplo, partner_acme para um parceiro externo ou finance_all para um grupo interno (o nome do grupo deles).

Como a tabela de permissões contém IDs de parceiros e nomes de grupos na mesma coluna, um único dashboard, uma única view e um único filtro cobrem ambos.

Como o visualizador nunca vê nem define o valor assinado, ele não pode alterá-lo. Um escopo desconhecido não corresponde a nenhuma linha, o que fornece um comportamento de negação por padrão (default-deny).

A mesma view e o mesmo filtro (WHERE viewer_scope = __aibi_external_value) atendem a ambos os públicos. Apenas a origem desse escopo é diferente:

Conceda acesso a grupos, não a pessoas

As organizações geralmente gerenciam o acesso por meio de grupos sincronizados de um provedor de identidade. Quando alguém entra no grupo Finance no Okta, seu acesso é mapeado para finance_all automaticamente, e nenhuma tabela de dados é alterada. Neste exemplo, finance_all é mapeado para todas as regiões e ops_west é mapeado para a região West.

Como o aplicativo descobre a quais grupos o visualizador pertence? Ele não pode depender de SQL durante a incorporação, porque a consulta é executada como a entidade de serviço e is_account_group_member() verificaria a identidade errada. O aplicativo deve resolver os grupos do visualizador no back-end, que pode ver o visualizador, antes de gerar o token.

Uma opção é executar o aplicativo no Databricks Apps com a autorização de usuário ativada.

Para um usuário interno conectado, a plataforma encaminha o contexto de identidade confiável para o back-end, incluindo o e-mail do visualizador e um token em nome de (OBO). O back-end usa esse token para chamar SCIM /Me como o visualizador e ler seus grupos.

Essa abordagem não exige direitos de administrador na entidade de serviço, pois o usuário está lendo seu próprio registro. Ela exige escopos de autorização do usuário, e o Apps OBO ainda está amadurecendo, portanto, valide-o em relação à implantação de destino antes de confiar nele.

Se nenhum grupo autorizado for encontrado, falhe de forma segura (fail closed) e recuse-se a gerar um token em vez de recorrer a uma identidade mais ampla, como o e-mail bruto.

Se um visualizador pertencer a vários grupos autorizados, resolva o resultado de forma determinística. Defina uma ordem de precedência ou mapeie vários grupos para um escopo canônico antes de gerar o token, para que o mesmo visualizador sempre receba um acesso consistente.

Parceiros externos são mais simples. Sem uma identidade do Databricks, o escopo deles é um ID de parceiro fixo atribuído no login. Mesmo token, mesmo filtro, sem consulta.

Uma limitação a ser considerada no projeto: um token assinado carrega um único external_value. Se um visualizador pertencer a vários grupos com permissões diferentes, um token ainda poderá representar apenas um escopo. Para o caso comum de uma função por pessoa, isso funciona bem.

Para uma união real de vários grupos, use um grupo de acesso total ou o caminho SQL direto abaixo, onde um filtro de linha pode aplicar um operador OR em todos os grupos. Um escopo composto (como JSON) pode ser compactado em external_value, mas a análise e a correspondência passam para o SQL do conjunto de dados e permanecem limitadas ao limite de payload de 1 KB.

Reforçando as garantias

O filtragem de linha fornece o comportamento básico: cada visualizador vê apenas suas próprias linhas. Três camadas adicionais reforçam os controles, e todas as três leem da mesma tabela de permissões.

Mascarar colunas confidenciais por visualizador

A segurança em nível de linha determina quais linhas um visualizador pode acessar. O mascaramento determina quais colunas eles podem ver, pois os parceiros externos geralmente não precisam do mesmo nível de detalhe que as equipes internas.

A flag mask_pii, true para parceiros e false para grupos internos, direciona a lógica de mascaramento na exibição protegida (a expressão CASE no SQL acima). O mesmo painel pode mostrar a um visualizador interno o e-mail completo, enquanto mostra a um parceiro um valor mascarado como ****@example.com. Quando as regras de mascaramento abrangem muitas tabelas e se tornam complexas, as máscaras de coluna do Unity Catalog e o controle de acesso baseado em atributos (ABAC) são a melhor solução de longo prazo; aqui, a exibição mantém o exemplo autocontido.

Negação por padrão, e comprove isso

Um escopo desconhecido não deve retornar nenhuma linha do painel e não deve revelar nada sobre a estrutura de dados subjacente: nenhum erro que sugira a estrutura, nenhum dado parcial, apenas um resultado vazio. Interromper o processo antes é ainda mais limpo: antes que o back-end gere um token, ele verifica a tabela de permissões e recusa qualquer escopo com direito a zero linhas. Igualmente importante, o escopo é derivado do visualizador autenticado, nunca de um parâmetro fornecido pelo cliente, de modo que um visualizador não pode solicitar o escopo de outro locatário.

O controle na emissão do token impede que um visualizador negado receba um token, o que é melhor do que depender do filtro SQL como a única proteção. Registrar tanto a emissão bem-sucedida de tokens quanto as solicitações negadas torna as decisões de autorização auditáveis: o visualizador negado simplesmente nunca aparece e, mesmo que uma solicitação passasse, um escopo desconhecido ainda não retornaria nenhuma linha do painel. Registrar o external_viewer_id e seu escopo nesses logs permite que cada decisão de autorização seja rastreada até um cliente ou usuário real durante uma auditoria.

Proteger o caminho SQL direto

Os controles de incorporação protegem o caminho do aplicativo. Um usuário do Databricks que consulta a tabela base diretamente representa uma ameaça separada. Adicione um filtro de linha do Unity Catalog à tabela base, associado à identidade e aos grupos do usuário que faz a consulta. Nesse caminho de consulta direta, is_account_group_member() avalia o usuário real e pode combinar todos os seus grupos autorizados. A exceção do publicador na função abaixo (current_user() igual à identidade de publicação) é uma permissão deliberada de emergência (break-glass) para a identidade que publica ou atualiza o painel, não um desvio geral do operador. Ela é opcional e de alto risco, portanto, inclua-a apenas onde for justificado e aprove-a por implantação.

Uma máscara de coluna para campos confidenciais funciona da mesma maneira. Esses controles do Unity Catalog são separados do caminho de incorporação: os visualizadores incorporados são limitados pelo escopo por meio de __aibi_external_value e da exibição de permissões, enquanto as consultas diretas do espaço de trabalho são protegidas pelo filtro de linha do Unity Catalog, que avalia a identidade e os grupos do chamador. Ambos os pontos de imposição usam a mesma tabela de permissões.

Antes de criar

Sobre "multilocação" (multi-tenancy). Trata-se de uma multilocação lógica e compartilhada: os parceiros externos são isolados uns dos outros, enquanto os funcionários internos recebem acesso baseado em grupo (baseado em função) dentro do próprio locatário da empresa. Todos os dados permanecem em tabelas compartilhadas; o token, o filtro de exibição e a tabela de permissões garantem a separação. O filtro de linha de SQL direto estende a mesma garantia para fora do aplicativo.

Quando usar este padrão. Use este padrão quando parceiros externos sem contas do Databricks e funcionários internos precisarem compartilhar o mesmo painel. Se cada visualizador for um usuário interno do Databricks, a incorporação básica com a segurança de linha e coluna do Unity Catalog poderá ser suficiente.

Restrições práticas e pontos de atenção. Verifique os seguintes limites do produto e detalhes operacionais na documentação atual antes da publicação:

• Os tokens têm vida curta (1 hora), portanto, o aplicativo precisa atualizá-los, especialmente se uma guia for deixada aberta. O SDK do cliente facilita isso: uma chamada de retorno (callback) getNewToken busca novamente no endpoint /api/token à medida que o token se aproxima do vencimento.
• Mantenha a combinação de `external_viewer_id` + `external_value` abaixo de 1 KB: use identificadores compactos, não blobs JSON ou e-mails longos.
• Limite de taxa de 20 carregamentos de painel por segundo por espaço de trabalho para incorporação externa. É importante saber disso para um portal B2B de grande porte.
• Use um `external_viewer_id` que não seja PII. Ele vai para os logs de auditoria, portanto, um ID de cliente ou usuário estável é melhor do que um nome completo ou e-mail bruto.
• Os downloads estão ativados por padrão. Visualizadores incorporados podem exportar CSV, TSV, Excel e PNG, a menos que um administrador do workspace desative os downloads. Confirme se os resultados exportados correspondem aos dados restritos ao visualizador esperados.
• Provisione grupos no nível da conta para o caminho SQL direto. Filtros de linha e máscaras do UC avaliam is_account_group_member() em relação a grupos no nível da conta, não locais do workspace. O caminho de incorporação nunca chama essa função.
• Atenção a tabelas de direitos grandes. Para milhares de escopos ou hierarquias profundas, mantenha as expressões de join e máscara simples e apoie-se no ABAC quando as regras ficarem complexas.

Principais conclusões

• Mantenha as regras de acesso em uma única tabela de direitos e use-a tanto para dashboards incorporados quanto para proteção de SQL direto.
• Registre um escopo de visualizador ou grupo em __aibi_external_value; não dependa de filtros editáveis pelo usuário.
• Use default-deny, mascaramento e filtros de linha do Unity Catalog como controles em camadas.
• A incorporação é apenas o primeiro passo; projetar e validar os controles de acesso é o trabalho crítico.

Chamada para ação

Comece com o guia fundamental, Como incorporar Dashboards de AI/BI do Databricks em aplicativos voltados para o cliente, depois aplique os padrões de direitos, mascaramento e default-deny descritos neste artigo. Para os controles de governança subjacentes, consulte a documentação de incorporação de AI/BI, além dos filtros de linha e máscaras de coluna do Unity Catalog e as orientações sobre ABAC.

(Esta publicação no blog foi traduzida utilizando ferramentas baseadas em inteligência artificial) Publicação original