Ajuda do Tableau Server no Windows

A partir do Tableau Server versão 2022.1, 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 Server e aplicativos externos nos quais o conteúdo do Tableau é inserido. No Tableau Server 2022.3, os aplicativos conectados ao Tableau estenderam seus recursos para dar suporte à autorização da API REST. E a partir de Tableau Server 2023.3, a autorização da API REST por meio de aplicativos conectados é respeitada pela API de metadados.

Os aplicativos conectados oferecem os seguintes benefícios:

• Restringir o acesso a qual conteúdo 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 Server 2023.3) em nome dos usuários usando o JSON Web Token (JWT)

Como funcionam os aplicativos conectados

A relação de confiança entre o site do Tableau Server 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. 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: 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: 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.

Fluxo de trabalho do aplicativo conectado

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 Server.

1. Como um administrador de servidor, entre no Tableau Server.

2. No painel esquerdo, selecione Configurações > Aplicativos conectados e clique no botão Novo aplicativo conectado.

3. 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:

         • O Tableau retirou a capacidade de inserir métricas no Tableau Server 2023.3.
         • Começando com Tableau Server 2024.2, você pode 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.

         

4. 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.

   

5. 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 Server. 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 ID 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 do usuário autenticado do Tableau Server.
  "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 do JWT deve estar dentro do período de validade máximo configurado O período máximo de validade pode ser configurado usando o comando tsm vizportal.oauth.connected_apps.max_expiration_period_in_minutes.
  "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 " (Adicionado no Tableau Server 2022.3) "tableau:metrics:embed" (Descontinuado no Tableau Server 2023.3) "tableau:ask_data:embed" Adicionado no Tableau Server versão 2023.1) Observações: Os valores devem ser passados como um tipo de lista. Para tableau:views:embed, o escopo respeita as permissões dos usuários já configuradas no Tableau Server 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.

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 = "username";
	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)
		.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"]
	},
		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

Para inserir fluxos de trabalho

Após a configuração do JWT, você deve adicionar o código de inserção ao seu aplicativo externo. Certifique-se de incluir o JWT válido que você configurou na Etapa 3 acima no componente da Web chamado pelo aplicativo externo.

Para obter mais informações sobre a inserção de conteúdo do Tableau, consulte um ou ambos os itens a seguir:

• Incorpore métricas, consulte o tópico Incorporar métricas a páginas(O link abre em nova janela) da Web na Ajuda do Tableau. (Em Tableau Server 2023.3, o Tableau retirou a capacidade de incorporar métricas.)
• Incorpore exibições e métricas usando a API de incorporação no Tableau v3(O link abre em nova janela).

Observação: para que os usuários se autentiquem com êxito, ao acessar o conteúdo incorporado, os navegadores devem ser configurados para permitir cookies de terceiros.

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 servidor ou administrador do site, entre no Tableau Server.

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, a 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 uma exibição ou métrica inserida ao usuário por meio de um aplicativo conectado, é necessário que o aplicativo conectado esteja ativado e o segredo seja 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 ao acessar o conteúdo inserido.

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://<your_server>/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 O Tableau Server 2024.2 descontinuará 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 Tableau Server 2023.3, o Tableau retirou a capacidade de incorporar métricas.)