Incorporação assinada

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

A incorporação assinada cria um URL especial do Looker para ser usado 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. Em seguida, você vai assinar o URL com uma chave secreta fornecida pelo Looker.

Para a 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 de Looks.

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

Hospedagem adequada para incorporação assinada

Em alguns navegadores, como o Safari ou aqueles com extensões instaladas que bloqueiam anúncios ou cookies de rastreamento, é padrão uma política de cookies que bloqueia cookies de terceiros. 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 do lado do servidor. Consulte a página de documentação Incorporação sem cookies para ver exemplos de configuração.

Se o recurso Inserção sem cookies não estiver ativado, o Looker vai usar cookies para autenticação do usuário. Nesse caso, não é possível tentar autenticar o iframe incorporado nos domínios em navegadores que bloqueiam cookies de terceiros (a menos que o usuário modifique as configurações de privacidade de cookies do navegador). Por exemplo, se você quiser incorporar informações em https://mycompany.com, vai precisar garantir que o Looker compartilhe 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 configurar o DNS necessário e ativar o uso de domínios personalizados. Isso permite que o Looker compartilhe o mesmo domínio do aplicativo incorporado e use 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 da sua instância do Looker.

Como controlar a visibilidade do cliente com um sistema fechado

Em uma configuração de incorporação assinada, os usuários do Looker apresentam dados aos próprios clientes ao mesmo tempo em que recebem clientes de diferentes empresas ou grupos que não deveriam conhecer uns aos outros. Nesse cenário, para proteger as informações particulares dos seus clientes, recomendamos configurar o Looker como um sistema fechado, também chamado de instalação multiusuário. Em um sistema fechado, o conteúdo é isolado para impedir que usuários de grupos diferentes saibam uns sobre os outros. Por esse motivo, recomendamos ativar a opção Sistema fechado antes de conceder acesso a usuários externos à sua instância.

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álise incorporada.

Como gerar o URL de incorporação assinado

Há várias maneiras de gerar o URL de incorporação assinado. Você pode usar um destes métodos:

Como codificar manualmente o URL de incorporação assinado

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

Como coletar as informações necessárias do Looker

Como ponto de partida para criar seu URL, primeiro você precisa determinar todas as informações que precisam ser incluídas. Você precisará dos seguintes itens:

Incorporar URL

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

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 da consulta 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 da Análise compõem o Query.client_id. O valor Query.client_id é uma string exclusiva que representa a consulta e as configurações de visualização.

Para incorporar uma visualização de consulta, extraia o valor Query.client_id da visualização de consulta e copie o Query.client_id no seu URL de incorporação.

Você pode usar a UI Análise do Looker para criar uma consulta com uma visualização compatível e copiar o valor Query.client_id do parâmetro qid= ou recuperar 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 valores de filtro do painel ou, se estiver ocultando valores de 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 legado do LookML 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 mudanças feitas no modo de desenvolvimento que afetam o conteúdo e 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 da mesma função.
  • 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 o conteúdo com base em modelos não incluídos no conjunto de modelos da função.

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 estiverem 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 visualizar Looks, dashboards ou Análises)
see_lookml_dashboards access_data Específico do modelo Permite que o usuário acesse os painéis do LookML
see_looks access_data Específico do modelo Permite que o usuário veja os Looks
see_user_dashboards see_looks Específico do modelo Permite que o usuário acesse painéis definidos pelo usuário e navegue por pastas em uma incorporação
explore see_looks Específico do modelo Permite que o usuário acesse as páginas "Explorar"
create_table_calculations explore Em toda a instância É necessário criar cálculos de tabela na Análise
create_custom_fields explore Em toda a instância ADICIONADO NA VERSÃO 22.4 Necessário para criar campos personalizados em uma Análise detalhada
can_create_forecast explore Em toda a instância ACRESCENTADO NA 22.12 Permite que os usuários criem ou editem previsões nas visualizações.
save_content see_looks Em toda a instância Permite que o usuário faça e salve alterações em Looks e dashboards
send_outgoing_webhook see_looks Específico do modelo Permite que o usuário programe entregas 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 entregas 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 as entregas 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 do usuário chamado "email") ou para um endereço de e-mail que esteja dentro das limitações definidas pela 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 dentro das limitações definidas pela lista de permissões de domínio de e-mail.
schedule_external_look_emails schedule_look_emails Específico do modelo Permite que o usuário programe envios 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 entregue conteúdo do Looker aos serviços de terceiros integrados ao Looker pelo Hub de ações do Looker. Essa permissão não está relacionada a ações de dados.
create_alerts see_looks Em toda a instância Permite que o usuário crie alertas nos Blocos do painel para receber notificações quando condições especificadas são 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 ao Slack.
download_with_limit see_looks Em toda a 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 Em toda a 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 ADICIONADO 21/14 Os usuários podem limpar o cache e atualizar dashboards incorporados, dashboards legados, blocos de dashboard, Looks e Explores.
see_drill_overlay access_data Específico do modelo Permite que o usuário faça detalhes sem precisar acessar a página "Explorar" completa.
embed_browse_spaces Nenhum Em toda a instância Ativa o navegador de conteúdo para que um usuário possa navegar por pastas de uma incorporação. Qualquer usuário de incorporação que receber a permissão embed_browse_spaces terá acesso a uma pasta de incorporação pessoal e à pasta Compartilhada da sua organização, se houver.

A permissão embed_browse_spaces é recomendada para usuários que têm a permissão save_content, para que possam procurar pastas ao selecionar onde salvar o conteúdo.

Para acessar o conteúdo em pastas, o usuário também precisa das permissões see_looks, see_user_dashboards e see_lookml_dashboards.
embed_save_shared_space Nenhum Em toda a instância ADICIONADO NA 21.4 Permite que o usuário que também tem a permissão save_content navegue até a pasta Compartilhada da organização, se houver uma, na caixa de diálogo Salvar. Os usuários que tiverem a permissão save_content, mas não embed_save_shared_space, só terão a opção de salvar conteúdo na pasta de incorporação pessoal deles.

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 ter acesso para Gerenciar acesso, Edição 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, edição à pasta Compartilhado salve conteúdo se ele tiver uma maneira alternativa de navegar até a pasta Compartilhado, como usar a opção Explorar aqui em um painel incorporado.

Acesso ao modelo

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

Atributos do usuário

Determine quais atributos do usuário ele deve ter, se houver. Você vai precisar do nome do atributo do usuário no Looker e do valor que o usuário deve ter para esse atributo.

Grupos

Determine a quais grupos o usuário deve pertencer, se for o caso. Você vai precisar dos IDs dos grupos, e não dos nomes dos grupos. Ao adicionar um usuário de incorporação assinado a um grupo do Looker, você pode gerenciar o acesso desse usuário às pastas do Looker. Os usuários de incorporação assinados têm acesso a todas as pastas compartilhadas com membros dos grupos do Looker.

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

Papéis incorporados

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

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

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

Nesse caso, o usuário incorporado herdará a capacidade de visualizar e explorar os dados no model_one, e o papel de incorporação criado com os parâmetros anteriores também concederá a capacidade de visualizar os dados em model_two.

Como criar o URL de incorporação

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

https://HOST/login/embed/INCORPORAR URL?PARÂMETROS&signature=ASSINATURA

Host

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

Incorporar URL

O URL de incorporação foi determinado anteriormente. Ele terá um formato como este:

  • /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/ aparecerá no seu URL final. isso está correto.

Se você estiver usando eventos JavaScript incorporados, adicione um embed_domain (o domínio em que o iframe está sendo usado) ao final do URL de incorporação, desta forma:

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

embed_domain é adicionado após o URL de incorporação e antes de qualquer parâmetro. Portanto, se você tivesse parâmetros existentes, como nonce=626, a adição de embed_domain seria semelhante a esta:

/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 sdk=2 ao final do URL de incorporação, como este:

/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 aproveite 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 parâmetros de URL a seguir 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, mas ela não pode ser repetida em uma hora e precisa ter menos de 255 caracteres.

Isso impede que um invasor envie novamente o URL de um usuário legítimo para coletar informações que não deveria ter.
String JSON "22b1ee700ef3dc2f500fb7"
time Valor obrigatório A hora atual como um carimbo de data/hora do UNIX. Número inteiro 1407876784
session_length Valor obrigatório O número de segundos que o usuário permanece conectado ao Looker, entre 0 e 2.592.000 segundos (30 dias). Número 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 assinados. Portanto, cada usuário precisa ter um ID exclusivo.

É possível criar um external_user_id para um usuário com qualquer string, desde que seja exclusivo para esse usuário. Cada ID é associado a um conjunto de permissões, atributos de usuário e modelos. Um único navegador pode oferecer suporte a apenas uma 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 no meio da sessão.

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

O uso do mesmo external_user_id para vários usuários ou para o mesmo usuário com várias permissões, atributos 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 aos quais o usuário deve ter acesso. Matriz de strings [

  "model_one",

  "model_two"

]
group_ids [] A lista de grupos do Looker dos quais o usuário precisa ser membro, se houver. Use IDs de grupos em vez de nomes. Matriz de strings ["4", "3"]
external_group_id "" Um identificador exclusivo do grupo ao qual o usuário pertence no aplicativo que está incorporando o Looker, se desejar.

Os usuários com permissão para salvar conteúdo e compartilhar um ID de grupo externo podem salvar e editar o conteúdo em uma pasta compartilhada do Looker chamada "Grupo". O parâmetro external_group_id é o único método disponível para criar grupos externos de usuários incorporados. Não é possível configurar grupos de usuários de incorporação externa na interface do Looker.
String JSON "Accounting"
user_attributes {} A lista de atributos do usuário, se houver. Contém uma lista de nomes de atributos do usuário seguidos pelo valor do atributo do usuário.

Se o modelo do LookML estiver localizado, use o atributo de usuário locale no URL de incorporação para especificar um idioma. Por exemplo, incluir o parâmetro user_attributes { "locale" : "fr_FR" } faria com que a incorporação carregasse 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 de posição vazio, por exemplo, access_filters={}. Marcador de posição vazio {}
first_name "" O nome do usuário. Se deixado em branco, first_name vai reter o valor da última solicitação ou será "Incorporar" se nenhum nome tiver sido definido. String JSON "Alice"
last_name "" O sobrenome do usuário. Se deixado em branco, last_name vai reter o valor da última solicitação ou será "Incorporar" se nenhum sobrenome tiver sido definido. String JSON "Jones"
user_timezone "" Se você tiver ativado os Fusos horários específicos do usuário, defina o valor da opção Fuso horário do espectador no menu suspenso Fuso horário no Look ou painel incorporado. Esse parâmetro não muda diretamente o fuso horário em que o conteúdo é mostrado. O usuário precisa 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 da equipe do Chat:se você quiser que o conteúdo incorporado seja padronizado para o fuso horário do espectador, 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 dashboard incorporado ou o Look com o fuso horário padrão definido como Fuso horário do visualizador, que vai usar o fuso horário do usuário por padrão para 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 e visualizar um item incorporado assinado, você poderá escolher se:

    1) Eles precisam acessar o item com as credenciais atuais.

    ou

    2) ele deverá sair e fazer login novamente com as credenciais de incorporação assinadas.
    Booleano (verdadeiro ou falso) true

    Assinatura

    O Looker usa a assinatura para verificar se o segredo de incorporação correto foi usado para gerar a assinatura no URL de incorporação e se os parâmetros no URL de incorporação não foram alterados. Se o segredo de incorporação ou os parâmetros do URL forem diferentes ou tiverem mudado, a assinatura não vai corresponder e a autenticação será rejeitada.

    Como resultado, a assinatura no URL de incorporação fornece uma prova criptograficamente forte de que o URL de incorporação não foi modificado em trânsito e de que ele foi criado por uma parte confiável que detém a chave secreta de incorporação.

    Para gerar a assinatura, siga 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
      • ID do usuário externo
      • Permissões
      • Modelos
      • IDs de grupo
      • ID do grupo externo
      • Atributos do usuário
      • Filtros de acesso (requer um marcador de posição vazio)
    2. Formatar todos os valores, exceto os campos Host e Embed URL, como JSON
    3. Concatene os valores com quebras de linha (\n)
    4. HMAC-SHA1 assina a string concatenada com a chave secreta de incorporação do Looker

    Codificação

    A etapa final é codificar o URL.

    Antes de codificar o URL, um URL incorporado com formato adequado que usa todos os parâmetros possíveis pode ter a seguinte 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, /embed//embed/ está correto no seu URL.

    Depois de codificar o URL, ele ficará assim:

    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 Url"

    A API Looker inclui o endpoint Criar URL de incorporação assinado, 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 o endpoint de API em um servidor da Web, ele precisa se autenticar na API Looker com privilégios de administrador. O domínio do servidor da Web também precisa estar listado na lista de permissões de domínios incorporados.

    Também é possível usar o API Explorer para gerar um URL assinado que use esse endpoint. É possível instalar o APIs Explorer na sua instância do Looker no Marketplace do Looker. Depois de gerado, o URL assinado precisa ser copiado exatamente e pode ser usado apenas uma vez. Caso contrário, ele vai falhar. O APIs Explorer também é útil para gerar um URL assinado e compará-lo a um URL assinado criado manualmente para solucionar problemas.

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

    Como testar o URL de incorporação

    Para testar seu URL final, cole-o no Validador de URI de incorporação na página Incorporar da seção Administrador do Looker. Essa opção não informa se os dados e as permissões que você imaginou foram configurados corretamente, mas pode validar se a autenticação está funcionando corretamente.