Escopos de acesso para aplicativos conectados

A partir do Tableau Server versão 2022.3 , ao usar aplicativos conectados ao Tableau, você pode chamar e acessar programaticamente a API REST do Tableau por meio de seu aplicativo personalizado em nome dos usuários do Tableau Server. O acesso à API REST é habilitado por um JSON Web Token (JWT) definido como parte da solicitação inicial de login. O JWT deve conter escopos que definam os métodos da API REST que estão disponíveis para seu aplicativo personalizado e seus usuários por meio do aplicativo conectado.

Autorize o acesso à API REST usando aplicativos conectados para:

• Aprimore a segurança — usar um JWT como token de portador é inerentemente mais seguro do que armazenar e gerenciar senhas de usuários administrativos por meio de arquivos .env em cofres
• Aumente a eficiência — usar um JWT como token de portador permite uma representação simplificada com uma solicitação para o endpoint de login em vez de duas solicitações
• Estenda e automatize integrações complexas do Tableau e consultas de back-end, como recuperação dinâmica de conteúdo e filtragem avançada

Ações de escopo

Os aplicativos conectados usam escopos que concedem acesso a ações de conteúdo ou administrativas por meio dos Métodos da API REST que dão suporte à autorização JWT (abaixo). Um escopo é uma cadeia de caracteres separada por dois pontos que começa com o namespace tableau, seguido pelo recurso do Tableau ao qual o acesso está sendo concedido, comodatasources e termina com a ação permitida no recurso, comoupdate.

As ações que um escopo pode realizar incluem:

• create
• read
• run
• update
• download
• delete

Por exemplo, um escopo que permite que seu aplicativo personalizado chame o método Atualizar fonte de dados(O link abre em nova janela) se parece com:

tableau:datasources:update

Tipos de escopo

O tipo de escopo que você usa depende do conteúdo ou da ação administrativa que deseja habilitar. Os escopos geralmente se enquadram em um dos seguintes tipos: leitura de conteúdo, individual, curinga e categoria cruzada.

• Escopo de leitura de conteúdo: o escopo de leitura de conteúdo, tableau:content:read, habilita métodos GET compatíveis para conteúdo do Tableau. Ao usar esse escopo, você habilita ações nas categorias da API REST. Mais especificamente, usando esse escopo, você habilita métodos GET para fontes de dados, métricas, exibições, pastas de trabalho, projetos e sites.

  Observação: para habilitar métodos GET para ações administrativas, como usuários e grupos, você pode usar seus escopos individuais.

• Escopos individuais: para habilitar conteúdo suportado e ações administrativas, você pode usar seus escopos individuais. Um escopo individual geralmente é associado a um único método e categoria da API REST.

  Exemplos:

  • Para permitir publicar ou atualizar uma ação de fonte de dados, você pode usar o escopo individual tableau:datasources:create outableau:datasources:update, respectivamente.
  • Para ações administrativas como adicionar ou remover usuários, você pode usar o escopo individual tableau:users:create ou tableau:users:delete, respectivamente.

  Observação: existem alguns escopos individuais que podem permitir ações nas categorias da API REST. Por exemplo, tableau:views:download permite ações nas categorias de API REST de exibição de dados e pastas de trabalho.

• Escopos curinga: para determinados escopos, você pode substituir a ação pelo caractere curinga (*) para habilitar ações com suporte em uma categoria de API REST específica.

  Exemplos:

  • Você pode usar o escopo curinga tableau:projects:* para habilitar as ações de criação, exclusão e atualização na categoria API REST de projetos.
  • Você pode usar o escopo curinga tableau:users:* para habilitar as ações de consulta, adição, exclusão e atualização na categoria API REST de usuários.

• Escopos de categoria cruzada: além do escopo de leitura de conteúdo, há alguns escopos adicionais que, se usados, habilitam ações com suporte em diferentes categorias de API REST.

  Exemplos:

  • Se estiver usando o escopo tableau:tasks:run, você habilitará ações nas fontes de dados e categorias de API REST de pastas de trabalho.
  • Novamente, se estiver usando o escopo tableau:views:download, habilite ações nas categorias API REST de exibição de dados e pasta de trabalho.
  • Se estiver usando escopos de permissões como tableau:permissions:update outableau:permissions:delete, você ativa ações nas fontes de dados, pastas de trabalho e categorias de API REST de projetos.

Resumo de como autorizar o acesso à API REST

A lista a seguir resume as etapas para solicitar acesso à API REST por meio de um JWT:

1. Crie um aplicativo conectado usando um dos seguintes métodos:
   • Configurar os Aplicativos conectados do Tableau para habilitar o SSO para conteúdo inserido
   • Registre o EAS para habilitar o SSO para conteúdo inserido
2. Gere um JWT válido — em tempo de execução, seu aplicativo personalizado gerará um JWT válido, configurado com os escopos que você incluiu
3. Faça uma solicitação de login(O link abre em nova janela) — seu aplicativo personalizado fará uma solicitação de login usando o JWT para retornar um token de credenciais do Tableau e um ID do site (LUID)
4. Use o token de acesso do Tableau em solicitações subsequentes — em chamadas subsequentes da API REST, use 1) o token de credenciais do Tableau como o valor de cabeçalho X-Tableau-Auth(O link abre em nova janela) e 2) o ID do site (LUID) no URI de solicitação

Exemplo

Por exemplo, suponha que você crie um aplicativo conectado usando confiança direta. Usando confiança direta, seu aplicativo personalizado que chama a API REST gera um JWT válido usando o ID do cliente e o segredo do cliente gerados pelo aplicativo conectado.

Escopos no JWT

Para autorizar com êxito o acesso à API REST, o JWT também deve conter os escopos que definem os recursos da API REST. Por exemplo, para habilitar vários métodos relacionados à fonte de dados, você pode incluir os seguintes escopos no JWT:

"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"

Ou

"tableau:content:read","tableau:datasources:*","tableau:tasks:run"

Observação: os valores devem ser passados como um tipo de lista.

URI de solicitação de logon

Para fazer uma chamada para a API REST, seu aplicativo personalizado deve primeiro fazer uma solicitação de logon para gerar um token de credenciais do Tableau.

POST https://myco/api/3.17/auth/signin

Corpo da solicitação

Para autorizar o acesso à API REST usando um JWT, o corpo da solicitação de logon deve conter o JWT válido, como no exemplo abaixo.

<tsRequest>
   <credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
    <site contentUrl="mycodotcom"/>
   </credentials>
</tsRequest>

Corpo de resposta

A solicitação de logon produz o seguinte corpo de resposta, que inclui o token de credenciais do Tableau.

<tsResponse>
   <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
    <site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
   </credentials>
</tsResponse>

Depois que o token de acesso do Tableau for gerado, adicione as credenciais de acesso do Tableau ao cabeçalho de todas as solicitações de API REST subsequentes.

Cabeçalho

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Todas as solicitações subsequentes da API REST usando o token de acesso do Tableau são delimitadas pelos escopos no JWT.

Métodos da API REST que dão suporte à autorização JWT

Os escopos a seguir podem ser associados ao aplicativo conectado para definir o acesso e os métodos que seu aplicativo personalizado pode ter à API REST(O link abre em nova janela) em nome dos usuários.

Observações:

• Para outros recursos da API REST não listados na tabela abaixo, você pode usar outros mecanismos de autorização para acessar os métodos. Para obter mais informações, consulte Métodos de autenticação(O link abre em nova janela) na Ajuda da API REST do Tableau Server.
• Para escopos compatíveis com a API de incorporação v3, consulte um dos seguintes:
  • Configurar os Aplicativos conectados do Tableau para habilitar o SSO para conteúdo inserido
  • Registre o EAS para habilitar o SSO para conteúdo inserido

Solucionar problemas de escopos

401001 - erro de login

Se você encontrar o erro 401001, o corpo da resposta de login será anexado com um dos seguintes códigos de erro adicionais específicos de aplicativos conectados: 16, 10084 ou 10085.

Por exemplo, no corpo da resposta a seguir, "10084" é o código de erro dos aplicativos conectados que você pode usar para ajudar a solucionar problemas ao fazer login no Tableau Server usando um JWT para autorização de API REST.

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

Para ajudar a resolver o problema, consulte a descrição do código de erro aplicável e suas possíveis causas.

• 16: Não foi possível encontrar o usuário — esse erro pode ocorrer porque o "sub" (nome de usuário) foi especificado

• 10084: Não foi possível analisar o token de acesso — esse erro pode ocorrer pelos seguintes motivos:

  • O JWT é inválido ou ocorreu um problema inesperado
  • O "aud " (público) incorreto foi especificado
  • Para confiança direta, houve um problema ao assinar o segredo

• 10085: Não foi possível buscar o segredo para verificar a assinatura do ID do cliente — esse erro pode ocorrer pelos seguintes motivos:

  • ID de cliente incorreto em "iss " especificada
  • Para confiança direta, "kid " (ID secreta) incorreta foi especificada
  • Para EAS, não foi possível recuperar as chaves do JWKSource

401002 - erro de acesso não autorizado

Se você encontrar o erro 401002 e tiver confirmado que possui as permissões apropriadas para fazer a solicitação, certifique-se de que o escopo incluído no JWT esteja correto e corresponda à solicitação que você está tentando fazer. Para obter uma lista de endpoints e escopos com suporte, consulte a seção Métodos da API REST que dão suporte à autorização JWT acima.