Primeiros passos com a incorporação de SSO

A incorporação de Logon único (SSO) é uma forma de apresentar os painéis "Looks", "Explores", "Painéis" ou "LookML" seguros para os usuários sem que eles precisem de um login separado do Looker. Em vez disso, os usuários vão ser autenticados no seu próprio aplicativo.

A incorporação de SSO funciona criando um URL especial do Looker que você usará em um iframe. O URL contém as informações que você quer compartilhar, o ID do usuário no seu sistema e as permissões que você quer conceder. Em seguida, assine o URL com uma chave secreta fornecida pelo Looker.

Hospedagem adequada para incorporação de SSO

Por padrão, alguns navegadores (Internet Explorer e Safari) utilizam uma política de cookies que bloqueia cookies de terceiros. Como o Looker usa cookies para autenticação de usuários, não é possível tentar autenticar o iframe incorporado em vários domínios nesses navegadores (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, verifique se o Looker está em um subdomínio, como https://analytics.mycompany.com.

Se o Looker estiver hospedando sua instância, fale com o suporte do Looker para definir a configuração de DNS necessária. Abra uma solicitação de suporte na Central de Ajuda do Looker clicando em Fale conosco.

Se você tiver uma instância do Looker hospedada pelo cliente, verifique se o aplicativo que vai usar a incorporação de SSO está no mesmo domínio base que sua instância do Looker.

Como controlar a visibilidade do cliente com um sistema fechado

É comum em uma configuração de incorporação de SSO que os usuários do Looker apresentem dados para seus próprios clientes e tenham clientes de diferentes empresas ou grupos que não devem conhecer uns aos outros. Nesse cenário, para proteger as informações particulares dos clientes, recomendamos configurar o Looker como um sistema fechado, também chamado de instalação multilocatária. Em um sistema fechado, o conteúdo é isolado, impedindo que usuários de grupos diferentes conheçam uns aos outros. Por isso, recomendamos que você ative a opção Sistema fechado antes de conceder acesso à sua instância aos 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álise incorporada.

Como gerar a chave secreta do Looker

Para confirmar que uma solicitação de incorporação de SSO é legítima e não foi falsificada por outra pessoa, primeiro você precisa gerar um "secret de incorporação". Para fazer isso, siga estas etapas:

  1. Acesse a página Incorporar na seção Administrador do Looker.
  2. Selecione Enabled na lista suspensa Embed SSO Authentication e clique em Update.
  3. Clique no botão Redefinir Secret para gerar a chave secreta incorporada. Não se esqueça de copiar este secret para um local seguro, porque não será possível recuperá-lo do Looker novamente sem redefini-lo. A redefinição da chave corrompe os embeddings que usavam a chave antiga.

Qualquer pessoa com acesso à chave secreta pode criar um URL para acessar qualquer modelo ao qual a instância do Looker esteja conectada, como qualquer usuário, com qualquer permissão. Proteja a chave secreta de incorporação do SSO, assim como você administraria credenciais na sua instância do Looker incorporada e mantenha a incorporação do SSO desativada se não estiver usando.

Como criar o URL incorporado

Para criar o URL adequado, é necessário escrever o código para codificar o URL corretamente com a chave secreta e gerar outros itens relacionados à segurança. Você pode encontrar diversos scripts de exemplo no nosso repositório do GitHub de exemplos de SSO. As seções a seguir explicam as informações que você precisará fornecer para esses scripts.

Coletar as informações necessárias do Looker

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

Incorporar URL

Recupere o URL da aparência, do painel ou do painel que você quer incorporar. Em seguida, remova o domínio e coloque /embed antes do caminho, desta maneira:

Item Padrão de URL normal Incorporar URL
Look https://instance_name.looker.com/
looks/4		 /embed/looks/4
Explore https://instance_name.looker.com/
explore/my_model/my_explore		 /embed/explore/my_model/my_explore
Painel definido pelo usuário https://instance_name.looker.com/
dashboards-next/1		 /embed/dashboards-next/1
Painel legado
definido pelo usuário		 https://instance_name.looker.com/
dashboards/1		 /embed/dashboards/1
dashboard do LookML https://instance_name.looker.com/
dashboards-next/my_model::my_dashboard		 /embed/dashboards-next/my_model::my_dashboard
LookML
painel legado		 https://instance_name.looker.com/
dashboards/my_model::my_dashboard		 /embed/dashboards/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 afetem o conteúdo e não tenham sido implantadas na produção não aparecerão em uma incorporação.

Permissões

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

  • Específico do modelo:esse tipo de permissão é aplicado somente 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 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 do SSO. As permissões que não estão na lista a seguir não são compatíveis com a incorporação de SSO:

Permissão Depende Tipo Definição
access_data Nenhum Específico do modelo Permite que o usuário acesse dados (necessário para visualizar visuais, painéis ou explorações)
see_lookml_dashboards access_data Específico do modelo Permite que o usuário veja os painéis do LookML
see_looks access_data Específico do modelo Permite que o usuário veja a aparência
see_user_dashboards see_looks Específico do modelo Permite que o usuário veja painéis definidos pelo usuário e procure pastas em uma incorporação
explore see_looks Específico do modelo Permite que o usuário veja as páginas "Explorar"
create_table_calculations explore Em toda a instância Necessidade de criar cálculos de tabela usando um recurso Explorar
save_content see_looks Em toda a instância Permite que o usuário faça e salve alterações em Aparências e painéis.
send_outgoing_webhook see_looks Específico do modelo Permite que o usuário programe painéis e aparências para um webhook arbitrário.
send_to_s3 see_looks Específico do modelo Permite que o usuário programe painéis e aparências em um bucket do Amazon S3.
send_to_sftp see_looks Específico do modelo Permite que o usuário programe painéis e aparências em um servidor SFTP
schedule_look_emails see_looks Específico do modelo Permite que o usuário programe painéis e aparências para serem enviados para o próprio e-mail (com um atributo do usuário chamado "email") ou para um endereço de e-mail 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 que esteja dentro das limitações definidas pela lista de permissões de domínios de e-mail.
schedule_external_look_emails schedule_look_
emails		 Específico do modelo Permite que o usuário programe painéis e aparências para que sejam enviados a qualquer 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 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 em blocos do painel para receber notificações quando as condições especificadas forem atendidas ou excedidas. Os usuários podem editar, duplicar e excluir seus próprios alertas e os alertas de Público 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 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 SQL resultantes da execução de consultas
see_drill_overlay access_data Específico do modelo Permite que o usuário faça o detalhamento 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 procurar pastas em uma incorporação. Qualquer usuário incorporado que receber a permissão embed_browse_spaces receberá acesso a uma pasta pessoal de incorporação e à pasta "Compartilhados" da sua organização, se houver.

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

Para ver 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 Permite que o usuário com a permissão save_content salve conteúdo na pasta compartilhada da organização, se houver. Os usuários que têm a permissão save_content, mas não a embed_save_shared_space, só podem salvar conteúdo na pasta de incorporação pessoal.

Acesso ao modelo

Determine a quais modelos LookML o usuário terá acesso. Isso será simplesmente uma lista de nomes de modelos.

Atributos do usuário

Determine quais atributos eles vão ter, se houver. Você precisará do nome do atributo do usuário no Looker, bem como do valor que o usuário deve ter para esse atributo.

Grupos

Determine a quais grupos o usuário deve pertencer, se houver. Você vai precisar dos IDs do grupo, e não dos nomes. Adicionar um usuário com SSO incorporado a um grupo do Looker permite gerenciar o acesso desse usuário às pastas do Looker. Os usuários com SSO incorporado vão ter acesso às pastas compartilhadas com os participantes 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 do SSO incorporado com o mesmo external_group_id vão ter acesso a uma pasta compartilhada chamada "Group", que é exclusiva do grupo externo.

Papéis incorporados

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

Por exemplo, digamos que você já tenha um grupo no Looker com o código 1, e esse grupo já tenha a permissão explore para um modelo chamado model_one, e você crie 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 conceder a capacidade de ver os dados no model_two.

Como criar o URL incorporado

Um URL incorporado de SSO tem o seguinte formato:

https://HOST/login/embed/URL INFORMAR?PARAMETERS&Signature=SIGNATURE

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 você não tiver ativado o encaminhamento de portas, como analytics.mycompany.com:9999.

Incorporar URL

O URL incorporado foi determinado anteriormente. Ele tem um formato como:

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/dashboards-next/1 ou /embed/dashboards/1
  • /embed/dashboards-next/my_model::my_dashboard ou /embed/dashboards/my_model::my_dashboard

Isso significa que o padrão /embed//embed/ vai aparecer no seu URL final. Está correto.

Se você estiver usando eventos JavaScript incorporados, adicione um embed_domain (o domínio em que o iframe está sendo usado) no fim do URL incorporado, assim:

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

embed_domain é adicionado depois do URL incorporado e antes de quaisquer parâmetros. Portanto, se você tiver parâmetros, como nonce=62, a adição de embed_domain vai ser semelhante a esta:

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

Se você estiver usando o SDK do embed, adicione o embed_domain e inclua sdk=2 no final do URL incorporado, da seguinte 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 aproveite os recursos adicionais fornecidos pelo SDK. O SDK não pode adicionar este parâmetro porque faz parte do URL do SSO assinado.

Parâmetros

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

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

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

Você cria essa string e pode ser qualquer valor. No entanto, esse valor precisa ser exclusivo para um determinado conjunto de permissões, atributos de usuário e modelos. Por exemplo, se o mesmo usuário tiver permissões diferentes em dois contextos, ele precisará de dois IDs de usuário externos diferentes.

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.		 String JSON "user-4"
permissions Sim A lista de permissões que o usuário precisa ter.

Consulte a seção Permissões nesta página para ver a lista de permissões.		 Matriz de strings [
  "access_data",
  "see_looks"
]
models Sim A lista de nomes de modelos aos quais o usuário deve ter acesso. Matriz de strings [
  "model_one",
  "model_two"
]
group_ids Não A lista de grupos do Looker de que o usuário deve ser membro, se houver. Use IDs de grupos em vez de nomes de grupos. Matriz de números inteiros [4, 3]
external_group_id Não Um identificador exclusivo do grupo a que o usuário pertence no aplicativo que incorpora o Looker, se desejado.

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

Se o modelo LookML for localizado, será possível usar o atributo de usuário locale no URL incorporado para especificar um idioma para a incorporação. Por exemplo, incluir o parâmetro user_attributes { "locale" : "fr_FR" } faria com que a incorporação carregasse francês como idioma.		 Hash de strings {
  "vendor_id" : "17",
  "company" : "xactness"
}
access_filters Sim No Looker 3.10, esse parâmetro foi descontinuado, mas ainda é obrigatório no URL. Use access_filters com um marcador vazio, por exemplo, access_filters={}. Marcador de posição vazio {}
first_name Não O nome do usuário. Se deixado em branco, first_name reterá o valor da última solicitação ou será “incorporado” se nenhum nome tiver sido definido. String JSON "Alice"
last_name Não O sobrenome do usuário. Se deixado em branco, last_name reterá o valor da última solicitação ou será “incorporado” se nenhum sobrenome tiver sido definido. String JSON "Jones"
user_timezone Não Se você tiver ativado os fusos horários específicos do usuário, o valor da opção Fuso horário de visualização será definido na lista suspensa Fuso horário no painel ou na aparência incorporada. Esse parâmetro não muda diretamente o fuso horário em que o conteúdo é exibido. O usuário precisará selecionar o fuso horário desejado na lista suspensa.

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

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

  • Adicione o parâmetro ?query_timezone=user_timezone ao URL incorporado. Por exemplo:

    /embed/dashboards/1?query_timezone=user_timezone
  • Salve o painel incorporado ou a visualização com o fuso horário padrão definido como Fuso horário de visualização, que vai usar o fuso horário do usuário por padrão tanto para usuários incorporados quanto para aqueles que não o incorporam.
    		•  String JSON ou nula "US/Pacific"

    - ou -

    null
    force_logout_login Sim Se um usuário normal do Looker já estiver conectado ao Looker e vir um item incorporado de SSO, será possível decidir se:

    1) ele deve ver o item com as credenciais atuais

    ou

    2) precisa ser desconectado e fazer login novamente com as credenciais de SSO.    		 Booleano (verdadeiro ou falso) true

    Todos os parâmetros anteriores são obrigatórios, mas qualquer parâmetro com "Não" na coluna "Valor necessário?" pode ser usado com o valor vazio. Por exemplo, use group_ids [] ou user_attributes {}.

    Assinatura

    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 grupos
      • ID do grupo externo
      • Atributos do usuário
      • Filtros de acesso (necessário um marcador vazio)
    2. Formatar todos os valores diferentes do URL de host e de incorporação como JSON
    3. Concatenar os valores com quebras de linha (\n)
    4. Assinar a string concatenada com o secret incorporado do Looker

    Codificação

    A etapa final é codificar o URL.

    Antes de codificar o URL, um URL incorporado incorporado adequadamente que use todos os parâmetros possíveis terá esta aparência:

    https://analytics.mycompany.com/login/embed//embed/dashboards-next/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 fica assim:

    https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards-next%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 da API create_sso_embed_url

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

    Para usar esse endpoint da API a partir de um servidor da Web, o servidor precisa conseguir 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 na instância do Looker para gerar um URL de SSO usando esse endpoint. Depois de gerado, o URL de SSO precisa ser copiado exatamente e só pode ser usado uma vez. Caso contrário, ele falhará. A documentação da API interativa também é útil para gerar um URL de SSO e compará-lo com um URL de SSO criado manualmente para solucionar problemas.

    Para mais informações sobre a API Looker, consulte a página Visão geral da API Looker.

    Como testar o URL incorporado

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