Ajuda do Tableau Cloud

A partir do começo de janeiro de 2022, os aplicativos conectados ao Tableau permitem uma experiência de autenticação perfeita e segura, facilitando uma relação de confiança explícita entre seu site do Tableau Cloud e aplicativos externos para:

• Restringir o acesso a conteúdo que pode ser inserido e onde esse conteúdo pode ser inserido
• Fornecer aos usuários a capacidade de acessar conteúdo inserido usando logon único (SSO) sem a necessidade de integração com um provedor de identidade (IdP)
• Fornecer aos usuários a capacidade de autenticar diretamente de seu aplicativo externo
• Autorizar programaticamente o acesso à API REST do Tableau (e à API de metadados a partir de Tableau Cloud Outubro de 2023) em nome dos usuários usando um JSON Web Token (JWT)

Como funcionam os aplicativos conectados

A relação de confiança entre o site do Tableau Cloud e o aplicativo externo é estabelecida e verificada por meio de um token de autenticação no padrão JSON Web Token (JWT), que usa um segredo compartilhado fornecido pelo aplicativo conectado ao Tableau e assinado pelo seu aplicativo externo.

Principais componentes de um aplicativo conectado

Os seguintes componentes do conectado trabalham em conjunto com o JWT em seu aplicativo externo para autenticar usuários e exibir conteúdo inserido.

• Segredos: os segredos são chaves compartilhadas pelo Tableau e seu aplicativo externo. Eles são usados em assinaturas que formam o JWT. Um segredo é necessário ao usar aplicativos conectados para autenticação de inserção ou autorização da API REST. Os segredos podem ser criados em um aplicativo conectado, não expiram e permanecem válidos até serem excluídos.
• Lista de permissões de domínio (pastas de trabalho inseridas somente): você pode especificar uma lista de domínios permitidos em cada aplicativo conectado. O conteúdo do Tableau inserido por meio de um aplicativo conectado só é permitido nos domínios especificados. Isso ajuda a garantir que o conteúdo seja exposto nos domínios protegidos e aprovados por sua empresa.
• Nível de acesso (pastas de trabalho inseridas somente): você pode especificar qual conteúdo pode ser inserido, por meio de um aplicativo conectado, associando um aplicativo conectado a um projeto ou a todos os projetos. Se você especificar um projeto, apenas o conteúdo do projeto selecionado pode ser inserido por meio do aplicativo conectado. Se quiser especificar vários projetos, você deverá usar a API REST do Tableau.

Observação: Para que o token de sessão seja válido, os relógios do aplicativo externo e do servidor que hospeda o aplicativo externo devem ser definidos como Tempo Universal Coordenado (UTC). Se um dos relógios usar um padrão diferente, o aplicativo conectado não será confiável.

Fluxo de trabalho do aplicativo conectado

Inserindo fluxos de trabalho

O diagrama abaixo ilustra como funciona a autenticação entre seu aplicativo externo (servidor Web e página da Web) e o aplicativo conectado.

1. O usuário visita a página da Web: quando um usuário visita o conteúdo inserido em uma página da Web, ela envia uma solicitação GET ao seu aplicativo externo para recuperar o HTML dela.
2. O aplicativo externo constrói um token de autenticação: o aplicativo externo constrói um JWT, que contém um segredo do aplicativo conectado (consulte a Etapa 3 abaixo para requisitos JWT adicionais) e o escopo de acesso do usuário para o conteúdo inserido. O segredo é assinado pelo aplicativo externo e é usado para verificação do relacionamento de confiança em uma etapa posterior.
3. O aplicativo externo responde com token de autenticação: o aplicativo externo responde à página com o JWT na URL do conteúdo inserido chamado pela página da Web.
4. A página da Web solicita conteúdo do Tableau: com a tentativa de carregar o conteúdo inserido, a página da Web chama a URL do conteúdo inserido, que envia uma solicitação GET ao Tableau.
5. O Tableau valida o token: o Tableau recebe o JWT e verifica a relação de confiança com o aplicativo personalizado ao identificar o aplicativo externo e o segredo compartilhado usado no JWT. Em seguida, o Tableau cria uma sessão para o usuário. A sessão não apenas respeita os escopos de inserção definidos no JWT, mas também as restrições especificadas no aplicativo conectado, incluindo os domínios e projetos permitidos.
6. O Tableau retorna o conteúdo com base no contexto de inserção restrito: o conteúdo inserido carrega apenas quando a página está em um domínio permitido e o conteúdo é publicado em um projeto permitido (se aplicável). O usuário autenticado só pode interagir com o conteúdo inserido pelo escopo definido no JWT.

Criar um aplicativo conectado

Etapa 1: criar um aplicativo conectado

Crie um aplicativo conectado na página Configurações do Tableau Cloud.

1. Como um administrador de site, entre no Tableau Cloud.

2. No painel esquerdo, selecione Configurações > Aplicativos conectados.

3. Clique na seta suspensa do botão Novo aplicativo conectado e selecione Confiança dieta.

4. Na caixa de diálogo Criar aplicativo conectado, faça uma das seguintes ações:

   1. Para fluxos de trabalho de autorização da API REST (incluindo fluxos de trabalho da API de metadados que usam a API REST para autenticação), na caixa de texto Nome do aplicativo conectado, insira um nome para o aplicativo conectado e clique no botão Criar.

      Observação: você pode ignorar o nível de acesso e a lista de permissões de domínio ao configurar um aplicativo conectado para autorização para API REST e API de metadados.

   2. Para inserir fluxos de trabalho, faça o seguinte:

      1. Na caixa de texto Nome do aplicativo conectado, insira um nome para o aplicativo conectado.

      2. No menu suspenso Aplica-se a, selecione Todos os projetos ou Apenas um projeto para controlar quais exibições ou métricas podem ser inseridas. Se você selecionar a opção "Somente um projeto", selecione o projeto específico para o escopo. Para obter mais informações sobre essas duas opções, consulte Nível de acesso (somente para inserir fluxos de trabalho) .

         Observações: 

         • Em Outubro de 2023 (Tableau 2023.3), o Tableau retirou a capacidade de inserir métricas.
         • Em fevereiro de 2024 (Tableau 2024.1), você poderá especificar vários projetos usando a API REST do Tableau. Para obter mais informações, consulte os métodos Criar aplicativo conectado(O link abre em nova janela) e Atualizar aplicativo conectado(O link abre em nova janela) na Ajuda da API REST.

      3. Na lista de permissões de Domínio, especifique os domínios usando as regras descritas em Formatação de domínio abaixo para controlar onde as exibições ou métricas podem ser inseridas.

      4. Quando terminar, clique no botão Criar.

         

5. Ao lado do nome dos aplicativos conectados, clique no menu de ações e selecione Ativar. Por motivos de segurança, um aplicativo conectado é definido como desabilitado por padrão quando criado.

   

6. Anote a ID do aplicativo conectado, também conhecido como ID do cliente, para usar na Etapa 3 abaixo.

   

Etapa 2: gerar um segredo

Você pode gerar um total de dois segredos para cada aplicativo conectado. O segundo segredo pode ser usado para fins de rotação de segredos, para ajudar a proteger contra problemas se um segredo for comprometido.

1. Na página de detalhes do aplicativo conectado que você criou na Etapa 1, clique no botão Gerar novo segredo.

2. Anote a ID secreta e o valor secreto para usar na Etapa 3 abaixo.

   

Etapa 3: configurar o JWT

Depois de gerar um segredo, você deseja habilitar seu aplicativo externo para enviar um JWT válido. O JWT é um padrão usado para transferir informações com segurança entre duas partes. O JWT é assinado pelo seu aplicativo externo para enviar informações com segurança ao Tableau Cloud. O JWT faz referência ao aplicativo conectado, ao usuário para o qual a sessão está sendo gerada e ao nível de acesso que o usuário deve ter.

Um JWT válido inclui as seguintes informações:

• ID do aplicativo conectado, também conhecido como ID do cliente, da Etapa 1

• ID secreta e valor secreto gerado na Etapa 2

• Reivindicações registradas e cabeçalho:

  Reivindicação	Nome	Descrição ou valor obrigatório
  "kid "	ID secreta	Obrigatório (no cabeçalho). O identificador de chave secreto do aplicativo conectado.
  "iss "	Emissor	Obrigatório (no cabeçalho). URI de emissor exclusivo que identifica o aplicativo de conexão confiável e a chave de assinatura.
  "alg "	Algoritmo	Obrigatório (no cabeçalho). Algoritmo de assinatura JWT. Apenas HS256 é compatível.
  "sub "	Assunto	Nome de usuário (endereço de e-mail) do usuário autenticado do Tableau Cloud.
  "aud "	Público	O valor deve ser: "tableau"
  "exp "	Data de validade	Um JWT válido não deve ter expirado. O tempo de expiração (em UTC) do JWT deve estar dentro do período de validade máximo, que é de 10 minutos.
  "jti "	ID do JWT	Necessário como uma declaração. A declaração JWT ID fornece um identificador exclusivo para o JWT e diferencia maiúsculas de minúsculas.
  "scp " Importante: não use "scope".	Escopo	Para fluxos de inserir pastas de trabalho, os valores com suporte incluem: "tableau:views:embed " “tableau:views:embed_authoring” "tableau:metrics:embed" (Removido em outubro de 2023 (Tableau 2023.3)) “tableau:ask_data:embed” (Descontinuado em fevereiro de 2024 (Tableau 2024.1)) Observações: Os valores devem ser passados como um tipo de lista. Para tableau:views:embed e tableau:views:embed_authoring, o escopo respeita as permissões dos usuários já configuradas no Tableau Cloud e permite que eles interajam com as ferramentas na exibição inserida, se disponível na exibição original. Recomendamos que o código de inserção exclua o parâmetro da barra de ferramentas. Para obter mais informações, consulte Problemas conhecidos (somente para inserir fluxos de trabalho) abaixo. Para fluxos de trabalho de autorização da API REST, consulte Métodos da API REST que dão suporte à autorização JWT. Para Fluxos de trabalho da API de metadados que usam a API REST para autenticação, o único escopo aceito é tableau:content:read.
  https://tableau.com/oda	Acesso sob demanda - reivindicação (habilitar capacidade)	Para fluxos de trabalho inseridos somente. O valor deve ser "true", e um ou mais grupos do Tableau Cloud devem ser especificados (consulte a próxima linha). Para obter mais informações, consulte a seção Acesso sob demanda (apenas fluxos de trabalho incorporados) abaixo.
  https://tableau.com/groups	Acesso sob demanda – reivindicação (especifique o nome do grupo)	Para fluxos de trabalho inseridos somente. O valor deve corresponder ao nome de um ou mais grupos no Tableau Cloud. Para obter mais informações, consulte a seção Acesso sob demanda (apenas fluxos de trabalho incorporados) abaixo.
  (Atributo do usuário)	(Valores de atributo do usuário)	Para fluxos de trabalho inseridos somente. Você pode incluir atributos de usuário no JWT. Em seguira, quando as funções de atributo do usuário são usadas no conteúdo inserido, o Tableau verifica o contexto do usuário autenticado e determina quais dados podem ser exibidos em tempo de execução. Observações: Verifique a Ajuda Embedding API v3(O link abre em nova janela) para problemas conhecidos que podem afetar seu fluxo de trabalho. Para que o atributo de usuário funcione, 1) você deve habilitar o Controle o acesso do usuário em fluxos de trabalho de autenticação configuração e 2) o autor do conteúdo deve criar um função de atributo do usuário(O link abre em nova janela). Os atributos de usuário diferenciam letras maiúsculas de minúsculas.

JWTs de exemplo

Aqui estão exemplos de JWTs nas linguagens Java e Python. Os exemplos Java e Python usam a biblioteca nimbus-jose-jwt e a biblioteca PyJWT, respectivamente.

Java

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
import com.nimbusds.jwt.*;

import java.util.*;

...

String secret = "secretvalue";
	String kid = "connectedAppSecretId";
	String clientId = "connectedAppClientId";
	List<String> scopes = new
ArrayList<>(Arrays.asList("tableau:views:embed"));
	String username = "user@domain.com";
	JWSSigner signer = new MACSigner(secret);
	JWSHeader header = new
JWSHeader.Builder(JWSAlgorithm.HS256).keyID(kid).customParam("iss", clientId).build();
	JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
		.issuer(clientId)
		.expirationTime(new Date(new Date().getTime() + 60 * 1000)) //expires in 1 minute
		.jwtID(UUID.randomUUID().toString())
		.audience("tableau")
		.subject("username")
		.claim("scp", scopes)
		.claim("https://tableau.com/oda", "true")
		.claim("https://tableau.com/groups", "Contractors", "Team C")
		.claim("Region", "East")
		.build();
	SignedJWT signedJWT = new SignedJWT(header, claimsSet);
	signedJWT.sign(signer);
	model.addAttribute("token", signedJWT.serialize());

Python

import jwt

token = jwt.encode(
	{
		"iss": connectedAppClientId,
		"exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=5),
		"jti": str(uuid.uuid4()),
		"aud": "tableau",
		"sub": user,
		"scp": ["tableau:views:embed", "tableau:metrics:embed"],
		"https://tableau.com/oda":"true",
		"https://tableau.com/groups": ["Contractors", "Team C"],
		"Region": "East"
	},
		connectedAppSecretKey,
		algorithm = "HS256",
		headers = {
		'kid': connectedAppSecretId,
		'iss': connectedAppClientId
        }
  )

Depois de configurar o JWT, quando o código for executado pelo aplicativo externo, ele gerará um token.

Etapa 4: próximas etapas

Gerenciar um aplicativo conectado

A página de aplicativos conectados é onde você pode gerenciar todos os aplicativos conectados para o seu site. Você pode realizar tarefas como criar, excluir e desabilitar aplicativos conectados, bem como revogar ou gerar novos segredos se os segredos existentes tiverem sido comprometidos.

1. Como um administrador de site, entre no Tableau Cloud.

2. No painel esquerdo, selecione Configurações > Aplicativos conectados.

3. Marque a caixa de seleção ao lado do aplicativo conectado que deseja gerenciar e execute um ou mais dos seguintes procedimentos:

   • Gere um novo segredo de acordo com a linha do tempo de rotação especificada pelas políticas de segurança da sua organização. Para gerar um segredo adicional, clique no nome do aplicativo conectado e, em seguida, clique no botão Gerar novo segredo. Um aplicativo conectado pode ter no máximo dois segredos. Ambos os segredos podem estar ativos ao mesmo tempo, não expiram e permanecem válidos até serem excluídos.

   • Revise os detalhes do aplicativo conectado clicando no nome do aplicativo conectado para ver quando o aplicativo conectado foi criado, seu ID, escopos de projeto e domínio e seus segredos.

   • Altere o escopo ou domínio do projeto, no menu Ações, selecione Editar. Faça as alterações e clique em Atualizar.

     Observação: se você alterar os escopos do projeto ou domínio e o conteúdo inserido não existir no novo projeto ou no novo domínio, a exibição ou métrica inserida não poderá ser exibida, e os usuários verão um erro ao acessar o conteúdo inserido.

   • Exclua um segredo clicando no nome do aplicativo conectado. Na página do aplicativo conectado, clique em Ações ao lado do segredo e selecione Excluir. Na caixa de diálogo de confirmação, selecione Excluir novamente.

     Observação: se o segredo do aplicativo conectado estiver sendo usado por um aplicativo externo, a exibição ou métrica inserida não poderá ser exibida depois que o segredo for excluído. Para obter mais informações, consulte Efeitos da desativação ou exclusão de um aplicativo conectado ou exclusão de um segredo abaixo.

   • Desative um aplicativo conectado, no menu Ações, selecione Desativar. Se o aplicativo conectado estiver sendo usado por um aplicativo externo, um exibição ou métrica inserida não poderá ser exibida depois que o aplicativo conectado for desativado. Para obter mais informações, consulte Efeitos da desativação ou exclusão de um aplicativo conectado ou exclusão de um segredo abaixo.

   

Efeitos da desativação ou exclusão de um aplicativo conectado ou exclusão de um segredo

Para exibir conteúdo incorporado ao seu usuário ou ativar o acesso à API RES por meio de um aplicativo conectado, o aplicativo conectado deve ser ativado e seu segredo gerado. Se o aplicativo conectado estiver sendo usado em seu aplicativo externo e for desativado ou excluído, ou seu segredo excluído ou substituído, os usuários receberão um erro 403.

Para evitar esse problema, certifique-se de que o aplicativo de conexão esteja habilitado, e o JWT esteja usando o ID secreto e o valor corretos.

Regras de lista de permissões de domínio (somente para inserir fluxos de trabalho)

A lista de permissões de domínio do aplicativo conectado permite que você restrinja o acesso ao conteúdo inserido do Tableau a todos os domínios ou alguns domínios; ou exclua alguns domínios ou bloqueie todos os domínios.

Opções de domínio

Você pode selecionar uma das duas opções ao configurar a lista de permissões de domínio de um aplicativo conectado:

• Todos os domínios: como opção padrão, ela permite acesso irrestrito ao conteúdo inserido.
• Apenas domínios específicos: esta opção oferece a capacidade de reduzir o escopo do acesso ao conteúdo inserido. Se você usar esta opção, siga as regras de formatação especificadas na seção a seguir, Formatação de domínio.

Formatação de domínio

Na caixa de texto da lista de domínios permitidos, você pode inserir um ou mais domínios usando os exemplos de formatação abaixo.

Observação: as regras de formatação de domínio também se aplicam ao usar os métodos de Aplicativo conectado(O link abre em nova janela) na API REST do Tableau.

Aqui estão alguns exemplos de formatação com base em cenários comuns:

Problemas conhecidos (somente para inserir fluxos de trabalho)

Existem alguns problemas conhecidos no uso de aplicativos conectados que serão abordados em uma versão futura.

• Recursos da barra de ferramentas: quando o conteúdo incorporado tem o parâmetro da barra de ferramentas definido, nem todos os recursos da barra de ferramentas funcionarão. Para contornar esse problema, recomendamos que você oculte o parâmetro da barra de ferramentas como no exemplo abaixo.

  <tableau-viz id='tab-viz' src='https://online.tableau.com/t/<your_site>/...'
  	toolbar='hidden'>
  </tableau-viz>

• Fontes de dados publicadas: as fontes de dados publicadas definidas como Solicitar usuário, para obter credenciais do banco de dados, não serão exibidas. Para contornar esse problema, se possível, recomendamos que os proprietários da fonte de dados incorporem suas credenciais de banco de dados.

• Objetos Pergunte aos dados em painéis inseridos: os objetos Pergunte aos dados em painéis inseridos não serão carregados. (Em Fevereiro de 2024 (Tableau 2024.1), o Tableau desativou o Pergunte aos dados.)

• Métricas e listas de permissão de domínio: as visualizações de métricas inseridas serão exibidas apesar das restrições de acesso que podem ser especificadas nas listas de permissão de domínio dos aplicativos conectados. Observação: os dados de métricas acessados em barras de ferramentas de exibições inseridas funcionarão conforme o esperado. (Em Outubro de 2023 (Tableau 2023.3), o Tableau retirou a capacidade de incorporar métricas.)