Implementar a segmentação no nível da linha para conteúdo incorporado do Looker

Criado por Christopher Seymour, analista sênior de dados, e Dean Hicks, engenheiro de relações com desenvolvedores

Com a segmentação no nível da linha, é possível limitar os dados que um usuário individual pode acessar com base nos valores armazenados em um ou mais campos do banco de dados. Este guia descreve métodos para implementar a segmentação no nível da linha em conteúdo incorporado do Looker e contém as seguintes seções:

Introdução

A funcionalidade de incorporação do Looker é um dos recursos mais poderosos e valiosos do produto. Se você está lendo este guia, provavelmente já está incorporando conteúdo do Looker no seu aplicativo ou pretende fazer isso em breve.

Este guia foi criado para ajudar você a entender melhor o design do recurso de incorporação do Looker e como implementar a segmentação em um aplicativo em que os parceiros podem gerenciar o acesso a várias marcas. Como é um aprofundamento sobre o assunto, a leitura é um pouco longa. Portanto, lembre-se de que este guia não é uma solução rápida para um problema simples, mas sim um elemento básico para ajudar você a gerenciar melhor todo o caso de uso de incorporação do Looker.

Visão geral do caso de uso

Este guia descreve um caso de uso comum em que sua empresa incorpora conteúdo do Looker no produto e atende a segmentos de usuários que precisam ver diferentes partes dos seus dados.

Para este caso de uso de incorporação assinada, suponha que você seja o administrador da sua instância do Looker. Você trabalha com dois tipos de usuários externos incorporados: clientes, que só podem acessar dados relacionados à marca específica deles, e parceiros, que podem acessar dados de várias marcas. Você tem um painel com alguns blocos que mostra para todos os clientes que usam seu produto, mas precisa que ele seja filtrado automaticamente para cada cliente. Assim, os painéis vão mostrar apenas os dados específicos de cada um. Os exemplos neste documento usam duas empresas fictícias: Hooli e Pied Piper.

Você tem uma tabela chamada products, que mostra algumas métricas de produtos para diferentes marcas. Cada marca corresponde a um usuário de incorporação diferente (com um external_user_id diferente) no aplicativo de incorporação assinado. Como cada usuário incorporado só pode ver os dados da própria marca, você tem uma Análise que usa um filtro de acesso em um atributo de usuário marca:

explore: products {
  access_filter: {
    field: products.brand
    user_attribute: brand
  }
}

Você tem um painel baseado nessa análise detalhada com dois blocos: um mostra o nome da marca, e o outro mostra o número de produtos dela.

Use o endpoint create_sso_embed_url para gerar URLs de incorporação desse painel para cada usuário de incorporação. Este exemplo usa duas marcas: Pied Piper e Hooli. Este é o corpo da solicitação que você usa na chamada create_sso_embed_url para a Pied Piper, com external_user_id pied_piper:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "pied_piper",
  "first_name": "PiedPiper",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper"}
}

O URL gerado para a Pied Piper mostra o painel desta forma:

Este é o corpo da solicitação usado na chamada create_sso_embed_url para a Hooli, com external_user_id hooli:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "hooli",
  "first_name": "Hooli",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Hooli"}
}

O URL gerado para a Hooli mostra o painel desta forma:

Voilà! O painel é filtrado de acordo com o valor de cada usuário incorporado para o atributo marca.

Análise detalhada

Muito legal! Mas e se eu quiser dar a um único usuário acesso a várias marcas? Como posso garantir que meus dados sejam vistos apenas pelos usuários relevantes?

Boas notícias! O recurso de incorporação assinada do Looker foi projetado para permitir que os desenvolvedores criem experiências de dados poderosas e personalizadas para os usuários, garantindo que a governança de dados definida pelo modelo de dados e pelas políticas de acesso ao conteúdo seja mantida.

Garantir que a governança de dados seja hermética é fundamental para oferecer essa experiência de dados eficiente. Leia mais para conhecer alguns conceitos e práticas recomendadas que você pode usar para criar a experiência ideal. Primeiro, uma breve visão geral de como tudo isso funciona.

Princípios básicos do embedding assinado do Looker

É importante lembrar que a autenticação e o gerenciamento de usuários do Looker no contexto de incorporação funcionam da mesma forma que no contexto não incorporado e na maioria dos outros aplicativos da Web.

Isso pode ser confuso no contexto de incorporação assinada do Looker, porque a etapa de autenticação assinada, as configurações do usuário e o próprio painel são combinados em um URL longo e complexo. No entanto, esse URL é usado para estabelecer a sessão, o que ainda se aplica mesmo depois que o URL é encurtado. Manter esse conceito em mente vai ajudar muito no seu sucesso ao criar ótimas experiências de dados.

Estrutura do URL de incorporação assinado

Este é um dos URLs de autenticação de incorporação assinados gerados pela chamada create_sso_embed_url com o corpo da solicitação para a Pied Piper:

https://mylookerinstance.cloud.looker.com/login/embed/%2Fembed%2Fdashboards%2F17?permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%5D&models=%5B%22thelook%22%5D&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r%2FtFuvE%3D&nonce=%22967729518a7dbb8a178f1c03a3511dd1%22&time=1696013242&session_length=300&external_user_id=%22pied_piper%22&access_filters=%7B%7D&first_name=%22Pied%22&last_name=%22Piper%22&user_attributes=%7B%22brand%22%3A%22Pied+Piper%22%7D&force_logout_login=true

Confira o mesmo URL decodificado e dividido em linhas individuais:

https://mylookerinstance.cloud.looker.com/login/embed/
/embed/dashboards/17
?permissions=["access_data","see_user_dashboards"]
&models=["thelook"]
&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r/tFuvE=
&nonce="967729518a7dbb8a178f1c03a3511dd1"
&time=1696013242
&session_length=300
&external_user_id="pied_piper"
&access_filters={}
&first_name="PiedPiper"
&last_name="User"
&user_attributes={"brand":"Pied Piper"}
&force_logout_login=true

Quando você acessa esse URL, algumas coisas acontecem:

  1. O Looker procura uma conta de usuário com external_user_id = pied_piper. Se não houver, o Looker vai criar uma conta de usuário com esse external_user_id.

  2. Os detalhes da conta do usuário atual, incluindo permissões, modelos, grupos (se especificados) e valores de atributos do usuário (se especificados), são substituídos pelos detalhes da conta especificados no URL.

  3. O Looker autentica o usuário e estabelece uma sessão para ele armazenando um cookie de sessão no navegador.

  4. Em seguida, o Looker redireciona para o URL de destino ou de redirecionamento especificado na chamada create_sso_embed_url:

    https://mylookerinstance.cloud.looker.com/embed/dashboards/17.

    Você pode ver esse URL de redirecionamento como um URL relativo codificado no URL de incorporação assinado original:

    %2Fembed%2Fdashboards%2F17

Embora as etapas 1 a 3 aconteçam em segundo plano automaticamente, e tudo o que o usuário final vê é o resultado final (o painel em si), essas etapas são fundamentalmente as mesmas que um usuário comum do Looker que não usa incorporação faz para se autenticar. Suponha que você queira que um usuário faça login com credenciais de usuário e senha. O processo seria algo assim:

  1. Você (o administrador do Looker) navega até o painel "Admin - Users" e usa a barra de pesquisa para verificar se já existe uma conta de usuário para essa pessoa. Se não houver, crie uma nova.

  2. Você (administrador do Looker) clica em Editar ao lado do usuário no painel "Admin - Usuários" e provisiona o usuário com permissões, modelos, grupos, valores de atributos do usuário e outros valores.

  3. O usuário acessa a página de login em https://mylookerinstance.cloud.looker.com/login e insere o nome de usuário e a senha. O Looker autentica o usuário e estabelece uma sessão para ele armazenando um cookie de sessão no navegador.

  4. Em seguida, o Looker redireciona para a página de destino (geralmente https://mylookerinstance.cloud.looker.com/browse).

O cookie de sessão se aplica a todas as guias na janela do navegador. Se o usuário começar no https://mylookerinstance.cloud.looker.com/browse, abrir uma nova guia do navegador e navegar para qualquer página a que suas permissões deem acesso, ela será carregada conforme o esperado usando o cookie de sessão já estabelecido na guia original do navegador.

O mesmo vale para usuários incorporados. Os usuários incorporados têm um pouco mais de limitação nas páginas que podem acessar na UI. Eles só podem acessar URLs de análises detalhadas, painéis e Explorar com o prefixo /embed. No entanto, eles ainda podem navegar manualmente até qualquer painel a que os detalhes da conta de usuário deles concedam acesso. Suponha que o URL de incorporação assinado original redirecione você para https://mylookerinstance.cloud.looker.com/embed/dashboards/17 em uma guia do navegador. Em seguida, abra uma nova guia do navegador e carregue um painel incorporado diferente que esteja na mesma pasta (e, portanto, tenha as mesmas restrições de acesso): https://mylookerinstance.cloud.looker.com/embed/dashboards/19.

Embora o URL de redirecionamento especificado no URL incorporado assinado original fosse para o painel 17, é possível ver que o painel 19 é carregado conforme o esperado se você inserir manualmente o URL em uma guia do navegador. Não foi necessário outro URL incorporado assinado para carregar um painel diferente.

O principal insight aqui é que todos os detalhes da conta de usuário estabelecidos no URL (permissões, atributos do usuário etc.) são aplicados a toda a sessão do usuário, não apenas ao painel específico especificado no URL assinado original. Em outras palavras, como o nome sugere, os atributos do usuário são uma característica do usuário, não do painel. Eles devem ser usados para determinar os níveis de acesso de um usuário específico em todo o aplicativo, não apenas em uma guia específica.

Acessar várias marcas ao mesmo tempo

Considere que você também tem parceiros externos que podem ter ou gerenciar várias marcas. Neste exemplo, um parceiro gerencia as marcas Pied Piper e Hooli.

A abordagem de uma perspectiva não incorporada

As sessões de usuário incorporadas e assinadas funcionam da mesma forma que as sessões de usuário regulares do Looker não incorporadas. Por isso, é útil reformular a abordagem problemática descrita anteriormente no contexto de uma sessão de usuário regular do Looker não incorporada e detalhar essas etapas para ajudar a entender como implementar essa solução de maneira mais robusta. Veja como seria esse fluxo de trabalho se você estivesse instruções a um usuário padrão de BI que tem acesso à interface do Looker:

  1. Você cria duas contas de usuário diferentes na página "Administrador" > "Usuários".
    1. Na página de edição da primeira conta de usuário, defina o valor do atributo de usuário marca como pied_piper.
    2. Na página de edição da segunda conta de usuário, defina o valor do atributo marca como hooli.
  2. Você envia e-mails de configuração de conta para ambas as contas de usuário ao parceiro.
  3. O parceiro configura credenciais de e-mail e senha separadas para cada conta.
  4. Você dá ao parceiro o link para o painel. (https://mylookerinstance.cloud.looker.com/dashboards/17) e informe que, para alternar o painel entre marcas, é necessário voltar à página de login em outra guia e inserir as credenciais de e-mail e senha da outra conta de usuário. Depois, carregue o painel novamente nessa guia.

O parceiro segue as instruções. No entanto, depois de inserir o nome de usuário e a senha da conta de usuário do Hooli na segunda guia do navegador e voltar para a primeira guia, onde o painel do Pied Piper já estava carregado, o parceiro clica no botão Recarregar. Para a surpresa do parceiro, o painel mostra os dados da Hooli.

Então, talvez você esteja pensando:

Espere… isso é muito inconveniente. Qual é a melhor maneira de fazer isso?

Sim! Esses cenários ajudam a ilustrar um princípio que já é trivial no contexto não incorporado, mas que pode ser obscurecido pelas abstrações do contexto incorporado: um único usuário humano deve ser associado a uma única conta de usuário do Looker com um único conjunto de valores de atributos do usuário.Isso também fica claro na explicação do external_user_id na documentação de incorporação assinada.

O Looker usa external_user_id para diferenciar usuários de incorporação assinada. Portanto, cada usuário precisa ter um ID exclusivo atribuído a ele.

Você pode criar um external_user_id para um usuário com qualquer string, desde que seja exclusiva para ele. Cada ID está associado a um conjunto de permissões, atributos do usuário e modelos. Um único navegador pode oferecer suporte a apenas um external_user_id ou sessão de usuário por vez. Não é possível fazer mudanças nas permissões ou nos atributos de um usuário no meio da sessão.

Acessar várias marcas ao mesmo tempo: o que NÃO fazer

Como em qualquer solução personalizável, há abordagens que você deve evitar. Por exemplo, uma implementação em que o app gera os URLs para external_user_ids usando as mesmas entradas na chamada create_sso_embed_url mostrada anteriormente e cria uma nova guia no app para carregar cada painel que o parceiro precisa acessar. É comum os desenvolvedores implementarem soluções como esta, o que resulta em um fluxo de trabalho incorreto para o usuário:

  1. Acesse a guia do painel da Pied Piper.
  2. Acesse a guia do painel do Hooli.
  3. Volte para a guia do painel do Pied Piper.
  4. Clique no botão Recarregar no painel do Pied Piper.

…o painel do Pied Piper mostra os dados da Hooli!

Você pode tentar uma abordagem semelhante, mas usar o mesmo external_user_id test_user para as duas chamadas create_sso_embed_url. Mas o comportamento é exatamente o mesmo: depois que a guia é recarregada com o painel da Pied Piper, ela mostra os dados da Hooli.

Como posso garantir que o painel de cada marca mostre apenas os dados dela?

Como usar as práticas recomendadas

Para aplicar a abordagem descrita na seção A abordagem de uma perspectiva não incorporada, você vai precisar de um único valor de atributo do usuário que conceda acesso a TODOS os dados que o parceiro deve ter no aplicativo. Para fazer isso, use um valor separado por vírgulas para o atributo marca Pied Piper,Hooli:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Para que essa sintaxe funcione, verifique se o atributo do usuário está definido como Filtro de string (avançado):

Observação: você ainda pode mudar o conjunto de atributos de usuário para um usuário se algo mudar nos níveis de acesso aos dados dele. Por exemplo, se o parceiro assumir a propriedade de uma terceira marca, adicione essa terceira marca à lista separada por vírgulas especificada para o atributo de usuário marca. Assim, quando ele sair e fizer login de novo, as mudanças serão aplicadas.

Filtrar os resultados do painel

Entendi que os atributos do usuário precisam especificar todos os dados que ele pode acessar no aplicativo. Mas se eu especificar os atributos do usuário dessa forma, os dados de todas essas marcas vão aparecer no meu painel. Como restringir os resultados de um painel específico a uma marca específica?

A maneira correta de filtrar um painel específico é usar os filtros de painel comuns. Isso pode parecer óbvio agora, mas já vimos pessoas ficarem presas aos atributos do usuário como a única maneira de aplicar filtros no contexto de incorporação. Talvez porque user_attributes seja um parâmetro no URL de incorporação assinado e "filtros" não seja.

Não se esqueça de exigir um valor de filtro e usar uma das opções de controle de seleção única, como o menu suspenso:

Verifique se o filtro está aplicado ao campo correto em todos os blocos necessários:

Agora, seu parceiro pode selecionar entre esses dois (e somente esses dois) valores, porque as opções disponíveis no menu suspenso são limitadas pelos atributos do usuário:

Pré-preenchimento dos filtros do painel

Ok, agora o painel pode ser filtrado para uma marca específica, mas eu quero que o valor do filtro já esteja definido para uma marca específica quando o usuário carregar o painel dessa marca no meu app.

É útil pensar em como isso funciona no contexto não incorporado. Como você envia a alguém um link para um painel que já tem um valor de filtro específico aplicado? Talvez você tenha notado que, ao selecionar um valor de filtro, ele aparece no URL do painel:

Inclua essa parte do URL no seu target_url para a chamada create_sso_embed_url:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Se você estiver usando o SDK de incorporação, poderá usar withFilters para especificar filtros iniciais a serem aplicados ao conteúdo incorporado:

https://looker-open-source.github.io/embed-sdk/classes/EmbedBuilder.html#withFilters

Se você estiver usando seu próprio script personalizado, adicione o filtro ao URL antes que o caminho seja codificado. Alguns valores já podem estar codificados na string de filtro (por exemplo, há um espaço codificado como + em ?Brand=Pied+Piper), então esses valores serão codificados duas vezes no URL final. Confira o artigo Painel incorporado do SO: definir o filtro do painel como parte do URL? Confira uma postagem na comunidade do Looker para saber mais sobre essas nuances. Se você ainda tiver problemas para aplicar os filtros, use essa postagem na comunidade para tirar dúvidas.

Ocultar os filtros do painel

Entendi como definir os filtros iniciais nos meus painéis, mas também não quero que o parceiro mude os filtros do painel. O valor do filtro deve ser determinado APENAS pelo painel que o parceiro acessou no meu app. Como posso ocultar os filtros do painel?

Para isso, use temas. Os temas são um recurso pago. Se você ainda não tiver ativado esse recurso na sua instância do Looker, entre em contato com a equipe de vendas do Looker para ativar.

Depois que esse recurso for ativado, acesse a seção Controles do painel na página "Admin - Temas" e desmarque a opção Mostrar barra de filtros:

Em seguida, você pode definir o tema como padrão ou aplicar o tema no URL dos seus painéis específicos. Novamente, isso entraria no target_url da chamada create_sso_embed_url:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli&theme=test_theme",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Há mais informações sobre como ocultar filtros de painel incorporados, incluindo alguns snippets de código do SDK de incorporação, neste tutorial do YouTube: Incorporar o Looker com filtros personalizados.

O resultado final deve ser idêntico à experiência do usuário da pergunta original:

Mas agora, como os valores de filtro são codificados nos respectivos URLs de destino incorporados ao app, o painel de cada marca sempre vai mostrar o painel filtrado para a marca correta, mesmo quando você alterna entre as guias.

Testar como outros usuários

Agora a experiência do usuário parece muito próxima do que eu havia imaginado originalmente. Mas, no meu caso de uso, o parceiro tem permissões diferentes e outras configurações de usuário que os usuários individuais com external_user_id=pied_piper e external_user_id=hooli não têm, o que leva a opções diferentes disponíveis na UI e a uma experiência do usuário um pouco diferente no geral. Quero permitir que um usuário veja tudo exatamente como os usuários pied_piper e hooli veem, como se a pessoa tivesse feito login como esses usuários. Como posso fazer isso?

Se você quiser que um usuário teste como cada um dos usuários individuais da marca, crie uma função sudo semelhante no app que carregue os URLs de incorporação para external_user_id=pied_piper quando o usuário estiver usando sudo como o usuário da Pied Piper e os URLs de incorporação para external_user_id=hooli quando o usuário estiver usando sudo como o usuário da Hooli. Também é possível usar o endpoint de API login_user para executar o comando sudo como o usuário da marca com a API se o app usar a API.

No entanto, se você pensar novamente no contexto não incorporado: na página "Administrador" > "Usuários", não é possível usar o sudo simultaneamente como vários usuários não incorporados em várias guias. A sessão sudo se aplica a toda a janela do navegador, assim como todas as outras sessões de usuário. Portanto, projete o sudo para sudo como apenas um usuário por vez. E, se você pensar bem, esse design é mais consistente com a experiência dos usuários que você está representando. O usuário pied_piper, por exemplo, tem acesso apenas ao painel da Pied Piper e não pode abrir outros painéis em outras guias. Portanto, não é possível abrir dashboards diferentes em guias diferentes ao usar o comando sudo como esse usuário.

Conclusão

Esperamos que este guia tenha sido útil e que você se sinta preparado para criar conteúdo incorporado assinado do Looker. Estamos sempre trabalhando para tornar o Looker a oferta de análise de dados incorporada mais flexível e robusta, e queremos saber sua opinião! Se você tiver dúvidas ou quiser saber mais, participe da comunidade do Looker e dos eventos da comunidade.