Incorporação assinada

A incorporação assinada é uma maneira de apresentar Looks, visualizações, Explores, painéis ou painéis LookML incorporados particulares aos usuários sem exigir que eles tenham um login separado do Looker. Em vez disso, os usuários serão autenticados por seu próprio aplicativo.

A incorporação assinada cria um URL especial do Looker que você vai usar em um iframe. O URL contém as informações que você quer compartilhar, o ID do usuário no sistema e as permissões que você quer que o usuário tenha. Depois, assine o URL com uma chave secreta fornecida pelo Looker.

Para incorporação pública, consulte a seção Incorporação pública com tags iframe da página de documentação Compartilhamento, importação e incorporação pública de Looks.

Antes de usar a incorporação assinada na sua instância do Looker, um administrador precisa ativar esse recurso no painel do administrador do Looker e criar uma chave secreta incorporada. Para ver instruções, consulte a página de documentação Primeiros passos na incorporação: como ativar a incorporação assinada.

Hospedagem adequada para incorporação assinada

Alguns navegadores (por exemplo, Safari ou com extensões instaladas que bloqueiam anúncios ou cookies de rastreamento) usam uma política de cookies que bloqueia cookies de terceiros por padrão. Quando o recurso Incorporação sem cookies está ativado, os navegadores que bloqueiam cookies de terceiros podem autenticar usuários no iframe incorporado em diferentes domínios. A autenticação de incorporação sem cookies requer configuração no lado do servidor. Consulte a página de documentação Incorporação sem cookies para ver exemplos de configuração.

Se o recurso Incorporação sem cookies não estiver ativado, o Looker vai usar cookies para a autenticação do usuário. Nesse caso, a tentativa de autenticar o iframe incorporado nos domínios não é possível em navegadores que bloqueiam cookies de terceiros (a menos que o usuário modifique as configurações de privacidade de cookies do seu navegador). Por exemplo, se você quiser incorporar informações em https://mycompany.com, verifique se o Looker compartilha o mesmo domínio, como https://analytics.mycompany.com. Nesse caso, se o Looker estiver hospedando sua instância, entre em contato com o suporte do Looker para definir a configuração de DNS necessária e permitir o uso do domínio personalizado. Dessa forma, o Looker pode compartilhar o mesmo domínio que o aplicativo incorporado e utilizar cookies primários, que são aceitos por padrão em todos os navegadores.

Se você tiver uma instância do Looker hospedada pelo cliente, verifique se o aplicativo que vai usar a incorporação assinada usa o mesmo domínio que sua instância do Looker.

Como controlar a visibilidade do cliente com um sistema fechado

É comum, em uma configuração de incorporação assinada, os usuários do Looker apresentarem dados aos próprios clientes, enquanto têm clientes de diferentes empresas ou grupos que não podem se conhecer. Nesse cenário, para proteger as informações particulares dos seus clientes, recomendamos que você configure o Looker como um sistema fechado, também chamado de instalação multilocatário. Em um sistema fechado, o conteúdo é isolado para evitar que usuários de diferentes grupos se saibam uns dos outros. Por isso, recomendamos que você ative a opção Sistema fechado antes de conceder acesso à sua instância a usuários externos.

Para mais informações, consulte as páginas de documentação Como projetar e configurar um sistema de níveis de acesso e Práticas recomendadas de segurança para análises incorporadas.

Como gerar o URL de incorporação assinada

Há várias maneiras de gerar o URL de incorporação assinada. Use um destes métodos:

Como codificar manualmente o URL de incorporação assinada

Para codificar o URL de incorporação assinada, primeiro colete as informações necessárias do Looker e, em seguida, crie o URL de incorporação assinada.

Coleta das informações necessárias do Looker

Para começar a criar seu URL, primeiro determine todas as informações que precisam ser incluídas. Você precisará dos seguintes itens:

Incorporar URL

Recupere o URL do Look, da Análise, da visualização de consulta ou do dashboard que você quer incorporar. Em seguida, remova o domínio e coloque /embed antes do caminho, da seguinte maneira:

Item Padrão de URL normal Incorporar URL
Look https://instance_name.looker.com/looks/4 /embed/looks/4
Explorar https://instance_name.looker.com/explore/my_model/my_explore /embed/explore/my_model/my_explore
Visualização de consultas https://instance_name.looker.com/explore/my_model/my_explore?qid=1234567890abcdefghij12

Os 22 caracteres alfanuméricos que seguem o parâmetro qid= no URL de análise compõem o Query.client_id. O valor Query.client_id é uma string única que representa a consulta e as configurações de visualização.

Para incorporar uma visualização de consulta, recupere o valor Query.client_id dela e copie o Query.client_id no URL incorporado.

Você pode usar a UI Explore do Looker para criar uma consulta com uma visualização compatível e copiar o valor Query.client_id do parâmetro qid=. Outra opção é extrair o Query.client_id com a API Looker usando o método Get Query, por exemplo.		 /embed/query-visualization/Query.client_id
Painel definido pelo usuário https://instance_name.looker.com/dashboards/1

Inclua os valores de filtro do painel ou, se ocultar os valores do filtro, o parâmetro hide_filter no URL do painel.
Painel legado definido pelo usuário https://instance_name.looker.com/dashboards-legacy/1 /embed/dashboards-legacy/1
dashboard do LookML https://instance_name.looker.com/dashboards/my_model::my_dashboard /embed/dashboards/my_model::my_dashboard
Dashboard do LookML legado https://instance_name.looker.com/dashboards-legacy/my_model::my_dashboard /embed/dashboards-legacy/my_model::my_dashboard

O conteúdo incorporado sempre reflete a versão de produção do conteúdo. As alterações feitas no modo de desenvolvimento que afetam o conteúdo e que não foram implantadas na produção não aparecem em uma incorporação.

Permissões

Um conjunto de permissões define o que um usuário ou grupo pode fazer. As permissões podem ser aplicadas de duas maneiras:

  • Específico do modelo:esse tipo de permissão é aplicado apenas aos conjuntos de modelos que fazem parte do mesmo papel.
  • Em toda a instância:esse tipo de permissão se aplica à instância do Looker como um todo. Os usuários incorporados com permissões em toda a instância podem realizar determinadas funções em toda a instância do Looker, mas não podem acessar conteúdo com base em modelos não incluídos no conjunto de modelos de papéis.

Determine as permissões que você quer que o usuário tenha. A lista a seguir mostra todas as permissões disponíveis para a incorporação assinada. As permissões que não estão na lista a seguir não são compatíveis com a incorporação assinada:

Permissão Depende de Tipo Definição
access_data Nenhum Específico do modelo Permite que o usuário acesse dados (necessário para acessar Looks, dashboards ou Explores)
see_lookml_dashboards access_data Específico do modelo Permite que o usuário veja painéis do LookML
see_looks access_data Específico do modelo Permite que o usuário veja Looks
see_user_dashboards see_looks Específico do modelo Permite que o usuário veja os painéis definidos pelo usuário e navegue pelas pastas de uma incorporação
explore see_looks Específico do modelo Permite que o usuário veja as páginas "Explorar"
create_table_calculations explore Na instância Era necessário criar cálculos de tabela em uma Análise
create_custom_fields explore Na instância ADDED 22.4 Era necessário criar campos personalizados em um Explore
can_create_forecast explore Na instância ADDED 22.12 Permite que os usuários criem ou editem previsões nas visualizações.
save_content see_looks Na instância Permite que o usuário faça e salve mudanças em Looks e dashboards
send_outgoing_webhook see_looks Específico do modelo Permite que o usuário programe envios de conteúdo do Looker para um webhook arbitrário
send_to_s3 see_looks Específico do modelo Permite que o usuário programe o envio de conteúdo do Looker para um bucket do Amazon S3
send_to_sftp see_looks Específico do modelo Permite que o usuário programe o envio de conteúdo do Looker para um servidor SFTP
schedule_look_emails see_looks Específico do modelo Permite que o usuário programe o envio de conteúdo do Looker para o próprio e-mail (se definido com um atributo de usuário chamado "email") ou para um endereço que esteja dentro das limitações da lista de permissões de domínios de e-mail. Permite que o usuário com permissões create_alerts envie notificações de alerta para um endereço de e-mail que está dentro das limitações definidas pela lista de permissões do domínio de e-mail.
schedule_external_look_emails schedule_look_emails Específico do modelo Permite que o usuário programe o envio de conteúdo do Looker para qualquer domínio de e-mail. Permite que o usuário com permissões create_alerts envie notificações de alerta para qualquer domínio de e-mail.
send_to_integration see_looks Específico do modelo Permite que o usuário envie conteúdo do Looker aos serviços de terceiros integrados ao Looker pelo Looker Action Hub. Essa permissão não está relacionada a ações de dados.
create_alerts see_looks Na instância Permite que o usuário crie alertas nos blocos do painel para receber notificações quando as condições especificadas forem atendidas ou excedidas. Os usuários podem editar, duplicar e excluir os próprios alertas e os públicos de outros usuários. Se o espaço de trabalho do Slack do usuário não estiver conectado à instância do Looker, o usuário não poderá criar alertas que enviem notificações para o Slack.
download_with_limit see_looks Na instância Permite que o usuário faça o download dos resultados de uma consulta com um limite aplicado
download_without_limit see_looks Na instância Permite que o usuário faça o download dos resultados de uma consulta sem limite aplicado
see_sql see_looks Específico do modelo Permite que o usuário veja o SQL para consultas e quaisquer erros de SQL resultantes da execução de consultas
clear_cache_refresh access_data Específico do modelo ADDED 21.14 Os usuários podem limpar o cache e atualizar os painéis incorporados, legados, os blocos do painel, os Looks e as Explores.
see_drill_overlay access_data Específico do modelo Permite que o usuário pesquise sem precisar acessar a página "Explorar" completa.
embed_browse_spaces Nenhum Na instância Ativa o navegador de conteúdo para que um usuário possa procurar pastas a partir de uma incorporação. Qualquer usuário incorporado com a permissão embed_browse_spaces vai ter acesso a uma pasta de incorporação pessoal e à pasta Compartilhada da sua organização, se houver uma.

A permissão embed_browse_spaces é recomendada para usuários com a permissão save_content. Assim, os usuários podem procurar pastas ao selecionar onde salvar o conteúdo.

Para ver o conteúdo das pastas, o usuário também precisa das permissões see_looks, see_user_dashboards e see_lookml_dashboards.
embed_save_shared_space Nenhum Na instância ADDED 21.4 Permite que o usuário que também tem a permissão save_content navegue até a pasta Compartilhado da organização, se houver, na caixa de diálogo Salvar. Os usuários com a permissão save_content, mas não a permissão embed_save_shared_space, só poderão salvar conteúdo na pasta de incorporação pessoal.

A permissão embed_save_shared_space não substitui as permissões de acesso ao conteúdo. Por exemplo, para permitir que o usuário salve na pasta Compartilhado, ele ainda precisa do acesso de Gerenciar acesso, Editar na pasta Compartilhado. Além disso, a falta da permissão embed_save_shared_space não impede que um usuário com a permissão save_content e o acesso Gerenciar acesso e edição à pasta Compartilhado salve o conteúdo nessa pasta, caso tenha uma maneira alternativa de acessar a pasta Compartilhado, por exemplo, usando a opção Explorar aqui em um painel incorporado.

Acesso ao modelo

Determine a quais modelos do LookML o usuário deve ter acesso. Será apenas uma lista de nomes de modelos.

Atributos do usuário

Determine os atributos que o usuário terá, se houver. Você vai precisar do nome e do valor do atributo do usuário do Looker.

Grupos

Determine a quais grupos o usuário deve pertencer. Você precisará dos IDs, não dos nomes dos grupos. Adicionar um usuário incorporado assinado a um grupo do Looker permite gerenciar o acesso desse usuário às pastas do Looker. Os usuários da incorporação assinada terão acesso a todas as pastas compartilhadas com os membros dos grupos do Looker.

Também é possível usar o parâmetro external_group_id para criar um grupo externo aos grupos comuns do Looker. Nesse caso, os usuários incorporados assinados com o mesmo external_group_id terão acesso a uma pasta compartilhada chamada "Grupo", que é exclusiva do grupo externo.

Funções incorporadas

Os parâmetros permissions e models criam um papel para o usuário incorporado. Ele aparece como um "Papel incorporado" na página Usuários da seção Administrador do Looker. Se os parâmetros permissions, models e group_ids estiverem todos especificados no URL incorporado, o papel incorporado será aditivo a qualquer papel já atribuído aos grupos listados no parâmetro group_ids. Esses papéis são iguais aos papéis padrão, já que todos no Looker são aditivos.

Por exemplo, digamos que você tenha um grupo no Looker com o ID 1 e ele já tenha a permissão explore para um modelo chamado model_one, e você criou um URL incorporado com os seguintes parâmetros:

  • group_ids = ["1"]
  • permissions = ["access_data","see_looks"]
  • models = ["model_two"]

Nesse caso, o usuário incorporado vai herdar a capacidade de ver e analisar os dados no model_one, e o papel de incorporação criado com os parâmetros anteriores também vai permitir o acesso aos dados no model_two.

Criar o URL de incorporação

Um URL de incorporação assinada tem o seguinte formato:

https://HOSThttps://URL CORPORATIVOhttps://PARÂMETROShttps://ASSINATURA

Host

O host é o local onde sua instância do Looker está sendo hospedada. Por exemplo, analytics.mycompany.com. Inclua o número da porta se não tiver ativado o encaminhamento de portas, como analytics.mycompany.com:9999.

Incorporar URL

O URL incorporado foi determinado anteriormente. O anúncio tem o seguinte formato:

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/query-visualization/Query.client_id
  • /embed/dashboards/1 ou /embed/dashboards-legacy/1
  • /embed/dashboards/my_model::my_dashboard ou /embed/dashboards-legacy/my_model::my_dashboard

Isso significa que o padrão /embed//embed/ vai aparecer no seu URL final, e essa informação está correta.

Se você estiver usando eventos JavaScript incorporados, adicione um embed_domain (o domínio em que o iframe é usado) ao final do URL incorporado, desta forma:

/embed/looks/4
⇨
/embed/looks/4?embed_domain=https://mywebsite.com

O embed_domain é adicionado depois do URL incorporado e antes de qualquer parâmetro. Portanto, se você tivesse parâmetros existentes, como nonce=626, a adição de embed_domain ficaria assim:

/embed/looks/4?nonce=626
⇨
/embed/looks/4?embed_domain=https://mywebsite.com?nonce=626

Se você estiver usando o SDK de incorporação, adicione embed_domain e também inclua sdk=2 no final do URL de incorporação, desta forma:

/embed/looks/4
⇨
/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2

O parâmetro sdk=2 permite que o Looker identifique que o SDK está presente e pode aproveitar os recursos adicionais fornecidos por ele. O SDK não pode adicionar esse parâmetro porque ele faz parte do URL assinado.

Parâmetros

Os seguintes parâmetros de URL são usados para especificar as informações necessárias para a incorporação assinada:

Parâmetro Valor padrão Descrição Tipo de dados Exemplo
nonce Valor obrigatório Qualquer string aleatória que quiser, mas não pode ser repetida dentro de uma hora e precisa ter menos de 255 caracteres.

Isso evita que um invasor reenvie o URL de um usuário legítimo para coletar informações que ele não deveria ter.		 String JSON "22b1ee700ef3dc2f500fb7"
time Valor obrigatório A hora atual como um carimbo de data/hora UNIX. Inteiro 1407876784
session_length Valor obrigatório O número de segundos que o usuário precisa permanecer conectado ao Looker, entre 0 e 2.592.000 segundos (30 dias). Inteiro 86400
external_user_id Valor obrigatório Um identificador para cada usuário no aplicativo que está incorporando o Looker. O Looker usa external_user_id para diferenciar os usuários de incorporação assinada. Por isso, cada usuário precisa ter um ID exclusivo atribuído.

Você pode criar uma external_user_id para um usuário com qualquer string que quiser, desde que ela seja exclusiva para esse usuário. Cada ID é associado a um conjunto de permissões, atributos do usuário e modelos. Um único navegador pode aceitar apenas um external_user_id ou sessão de usuário por vez. Nenhuma alteração pode ser feita nas permissões ou nos atributos de um usuário durante a sessão.

Por motivos de segurança, verifique se você não está usando o mesmo external_user_id em diferentes sessões de incorporação para diferentes usuários interativos e se não está usando o mesmo external_user_id para um único usuário com permissões, valores de atributo ou acesso ao modelo distintos.

Usar o mesmo external_user_id para vários usuários ou para o mesmo usuário com diversas permissões, atributos de usuários ou conjuntos de modelos pode fazer com que os dados fiquem visíveis para usuários que, de outra forma, não teriam acesso a eles.		 String JSON "user-4"
permissions Valor obrigatório A lista de permissões que o usuário deve ter.

Consulte a seção Permissões nesta página para ver a lista de permissões permitidas.		 Matriz de strings [

  "access_data",

  "see_looks"

]
models Valor obrigatório A lista de nomes de modelos a que o usuário deve ter acesso. Matriz de strings [

  "model_one",

  "model_two"

]
group_ids [] A lista de grupos do Looker de que o usuário vai participar, se houver. Use IDs de grupos em vez de nomes de grupos. Matriz de strings ["4", "3"]
external_group_id "" Um identificador exclusivo do grupo a que o usuário pertence no aplicativo que está incorporando o Looker, se desejado.

Os usuários que têm permissão para salvar conteúdo e compartilhar um ID de grupo externo vão poder salvar e editar o conteúdo em uma pasta compartilhada do Looker chamada "Grupo".		 String JSON "Accounting"
user_attributes {} A lista de atributos do usuário que o usuário deve ter, se houver. Contém uma lista de nomes de atributos do usuário seguidos pelo valor do atributo do usuário.

Se o modelo LookML estiver localizado, será possível usar o atributo de usuário locale no URL da incorporação para especificar um idioma. Por exemplo, incluir o parâmetro user_attributes { "locale" : "fr_FR" } faria com que a incorporação carregue o francês como idioma.		 Hash de strings {

  "vendor_id" : "17",

  "company" : "xactness"

}
access_filters Valor obrigatório No Looker 3.10, esse parâmetro foi removido, mas ainda é obrigatório no URL. Use access_filters com um marcador vazio, por exemplo, access_filters={}. Marcador de posição vazio {}
first_name "" O nome do usuário. Se deixado em branco, first_name manterá o valor da última solicitação ou será "Embed" (Incorporar) se nenhum nome tiver sido definido. String JSON "Alice"
last_name "" O sobrenome do usuário. Se deixado em branco, last_name manterá o valor da última solicitação ou será "Embed" (Incorporar) se nenhum sobrenome tiver sido definido. String JSON "Jones"
user_timezone "" Se você tiver ativado Fusos horários específicos do usuário, defina o valor da opção Fuso horário do espectador na lista suspensa Fuso horário do Look ou do dashboard incorporado. Esse parâmetro não altera diretamente o fuso horário em que o conteúdo é exibido. O usuário precisará selecionar um fuso horário no menu suspenso.

Consulte os valores válidos na página de documentação Referência de fuso horário de incorporação assinada.

Dica para a equipe do Chat:se você quiser que o conteúdo incorporado seja definido por padrão no fuso horário do leitor, use um dos seguintes métodos:

  • Adicione o parâmetro ?query_timezone=user_timezone ao URL de incorporação. Exemplo:

    /embed/dashboards/1?query_timezone=user_timezone
  • Salve o painel incorporado ou o Look com o fuso horário padrão definido como Fuso horário do espectador, que vai usar o fuso horário do usuário por padrão para os usuários incorporados e não incorporados.
    		•  String JSON ou nulo "US/Pacific"

    - ou -

    null
    force_logout_login Valor obrigatório Se um usuário normal do Looker já estiver conectado ao Looker e visualizar um item incorporado assinado, você terá as seguintes opções:

    1) os usuários devem acessar o item com as credenciais atuais.

    ou

    2) eles devem ser desconectados e conectados novamente com as credenciais de incorporação assinadas.    		 Booleano (verdadeiro ou falso) true

    Assinatura

    Para gerar a assinatura, você precisa seguir estas etapas.

    1. Reúna os seguintes valores de parâmetro nesta ordem:
      • Host, seguido por login/embed/ (por exemplo, analytics.mycompany.com/login/embed/)
      • Incorporar URL
      • Valor de uso único
      • Hora atual
      • Duração da sessão
      • User-ID externo
      • Permissões
      • Modelos
      • IDs de grupos
      • ID do grupo externo
      • Atributos do usuário
      • Filtros de acesso (requer um marcador vazio)
    2. Formate todos os valores como JSON, exceto "Host" e "Incorporar URL".
    3. Concatenar os valores com quebras de linha (\n)
    4. Assinar HMAC a string concatenada com sua chave secreta incorporada do Looker

    Codificação

    A etapa final é codificar o URL.

    Antes de codificar o URL, um URL incorporado com formato correto e que usa todos os parâmetros possíveis pode ter esta aparência:

    https://analytics.mycompany.com/login/embed//embed/dashboards/1?
nonce="22b1ee700ef3dc2f500fb7"&
time=1407876784&
session_length=86400&
external_user_id="user-4"&
permissions=["access_data","see_user_dashboards","see_looks"]&
models=["model_one","model_two"]&
group_ids=[4,3]&
external_group_id="Allegra K"&
user_attributes={"vendor_id":"17","company":"xactness"}&
access_filters={}&
first_name="Alice"&
last_name="Jones"&
user_timezone="US/Pacific"&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

    Conforme observado anteriormente, é correto que /embed//embed/ apareça no seu URL.

    Depois de codificar o URL, ele terá esta aparência:

    https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards%2F1?
nonce=%2222b1ee700ef3dc2f500fb7&%22&
time=1407876784&
session_length=86400&
external_user_id=%22user-4%22&
permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
models=%5B%22model_one%22%2C%22model_two%22%5D&
group_ids=%5B4%2C3%5D&
external_group_id=%22Allegra%20K%22&
user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
access_filters%7B%7D%26%0A
first_name=%22Alice%22&
last_name=%22Jones%22&
user_timezone=%22US%2FPacific%22&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

    Como usar o endpoint de API Create Signed Embed Url

    A API Looker inclui o endpoint Create Signed Embed Url, que usa um conjunto de parâmetros de incorporação assinados que inclui o URL do conteúdo que você quer incorporar e retorna um URL completo, codificado e assinado criptograficamente.

    Para usar esse endpoint de API em um servidor da Web, o servidor da Web precisa conseguir fazer a autenticação na API Looker com privilégios de administrador. O domínio do servidor da Web também precisa estar na lista de permissões de incorporação de domínios.

    Também é possível usar o API Explorer para gerar um URL assinado que usa esse endpoint. Instale o API Explorer na sua instância do Looker pelo Marketplace do Looker ou confira uma versão pública no Portal de desenvolvedores do Looker. Depois de gerado, o URL assinado precisa ser copiado e usado apenas uma vez. Caso contrário, ocorrerá uma falha. O API Explorer também é útil para gerar um URL assinado e compará-lo a um URL assinado criado manualmente para fins de solução de problemas.

    Para mais informações sobre a API Looker, consulte a página de documentação Introdução à API Looker.

    Testar o URL de incorporação

    Para testar o URL final, cole-o no Incorporar validador de URI na página Incorporar da seção Administrador do Looker. Embora essa opção não informe se os dados e as permissões que você imagina foram configurados corretamente, ela pode validar se a autenticação está funcionando.