Alcances del acceso para aplicaciones conectadas

A partir de Tableau Server 2022.3, con las aplicaciones conectadas de Tableau, puede llamar y acceder mediante programación a la API de REST de Tableau a través de su aplicación personalizada en nombre de los usuarios de Tableau Server. El acceso a la API de REST está habilitado por un JSON Web Token (JWT) definido como parte de la solicitud de inicio de sesión inicial. El JWT debe contener alcances que definan los métodos de la API de REST que están disponibles para su aplicación personalizada y sus usuarios a través de la aplicación conectada.

Autorice el acceso a la API de REST usando aplicaciones conectadas para:

• Mejore la seguridad: el uso de un JWT como token portador es intrínsecamente más seguro que almacenar y administrar contraseñas de usuarios administradores a través de archivos .env en bóvedas
• Mejorar la eficiencia: el uso de un JWT como token de portador permite una suplantación simplificada con una solicitud al punto final de inicio de sesión en lugar de dos solicitudes
• Extiender y automatizar integraciones complejas de Tableau y consultas de back-end, como la recuperación de contenido dinámico y el filtrado avanzado.

Acciones de ámbito

Las aplicaciones conectadas usan alcances que otorgan acceso al contenido o acciones administrativas a través de los Métodos de la API de REST que admiten la autorización JWT (a continuación). Un alcance es una cadena separada por dos puntos que comienza con el espacio de nombrestableau, seguido del recurso de Tableau al que se otorga acceso, como datasources y finaliza con la acción que está permitida en el recurso, comoupdate.

Las acciones que un alcance puede tomar incluyen:

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

Por ejemplo, un alcance que permite que su aplicación personalizada llame al método Actualizar fuente de datos(El enlace se abre en una ventana nueva) se ve así:

tableau:datasources:update

Tipos de alcance

El tipo de ámbito que utilice depende del contenido o la acción administrativa que desee habilitar. Los ámbitos generalmente se dividen en uno de los siguientes tipos: lectura de contenido, individual, comodín y categoría cruzada.

• Ámbito de lectura de contenido: el ámbito de lectura de contenido, tableau:content:read, habilita los métodos GET admitidos para el contenido de Tableau. Cuando usa este ámbito, habilita acciones en las categorías de API de REST. Más específicamente, al usar este ámbito, habilita métodos GET para fuentes de datos, métricas, vistas, libros de trabajo, proyectos y sitios.

  Nota: Para habilitar métodos GET para acciones administrativas, como usuarios y grupos, puede usar sus ámbitos individuales.

• Ámbitos individuales: para habilitar el contenido compatible y las acciones administrativas, puede utilizar sus ámbitos individuales. Un ámbito individual generalmente se asocia con un solo método y categoría de API de REST.

  Ejemplos:

  • Para habilitar la acción de publicar o actualizar una fuente de datos, puede usar el ámbito individual tableau:datasources:create o tableau:datasources:update, respectivamente.
  • Para acciones administrativas como agregar o eliminar usuarios, puede usar los ámbitos tableau:users:create o tableau:users:delete, respectivamente.

  Nota: Hay algunos ámbitos individuales que pueden habilitar acciones en las categorías de API de REST. Por ejemplo, tableau:views:download habilita acciones en las categorías de API de REST de ver datos y libros de trabajo.

• Ámbitos comodín: para ciertos ámbitos, puede reemplazar la acción con el carácter comodín (*) para habilitar las acciones admitidas dentro de una categoría de API de REST específica.

  Ejemplos:

  • Puedes usar el ámbito comodín tableau:projects:* para habilitar las acciones de creación, eliminación y actualización en la categoría de API de REST de proyectos.
  • Puedes usar el ámbito comodín tableau:users:* para habilitar las acciones de consulta, adición, eliminación y actualización en la categoría de la API de REST de los usuarios.

• Ámbitos de categorías cruzadas: además del ámbito de lectura de contenido, existen algunos ámbitos adicionales que, si se utilizan, habilitan acciones admitidas en diferentes categorías de API de REST.

  Ejemplos:

  • Si usa el ámbito tableau:tasks:run, habilita acciones en las fuentes de datos y las categorías de API de REST de libros de trabajo.
  • Nuevamente, si usa el ámbito tableau:views:download, habilita acciones en las categorías de la API de REST de los datos de vista y del libro de trabajo.
  • Si usa ámbitos de permisos como tableau:permissions:update o tableau:permissions:delete, habilita acciones en las fuentes de datos, libros de trabajo y categorías de API de REST de proyectos.

Resumen de cómo autorizar el acceso a la API de REST

La siguiente lista resume los pasos para solicitar acceso a la API de REST a través de un JWT:

1. Cree una aplicación conectada usando uno de los siguientes métodos:
   • Configure las aplicaciones conectadas de Tableau para habilitar el inicio de sesión único para el contenido incrustado Configure las aplicaciones conectadas de Tableau para habilitar el inicio de sesión único para el contenido incrustado
   • Registre EAS para habilitar SSO para contenido insertado
2. Genere un JWT válido: en el momento de la ejecución, su aplicación personalizada generará un JWT válido, configurado con los ámbitos que ha incluido
3. Realizar una solicitud de inicio de sesión(El enlace se abre en una ventana nueva): su aplicación personalizada realizará una solicitud de inicio de sesión mediante el JWT para devolver un token de credenciales de Tableau y un ID de sitio (LUID)
4. Utilice el token de acceso de Tableau en las solicitudes posteriores: en las llamadas posteriores a la API de REST, utilice 1) el token de credenciales de Tableau como el valor de encabezado X-Tableau-Auth(El enlace se abre en una ventana nueva) y 2) el ID del sitio (LUID) en el URI de la solicitud

Ejemplo

Por ejemplo, suponga que crea una aplicación conectada mediante confianza directa. Al usar la confianza directa, su aplicación personalizada que llama a la API de REST genera un JWT válido usando la identificación del cliente y el secreto del cliente generado por la aplicación conectada.

Alcances en el JWT

Para autorizar correctamente el acceso a la API de REST, el JWT también debe contener los ámbitos que definen las capacidades de la API de REST. Por ejemplo, para habilitar varios métodos relacionados con la fuente de datos, puede incluir los siguientes ámbitos en el JWT:

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

O

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

Nota: Los valores de alcance deben pasarse como un tipo de lista.

URI de solicitud de inicio de sesión

Para realizar una llamada a la API de REST, su aplicación personalizada primero debe realizar una solicitud de inicio de sesión para generar un token de credenciales de Tableau.

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

Cuerpo de la solicitud

Para autorizar el acceso a la API de REST mediante un JWT, el cuerpo de la solicitud de inicio de sesión debe contener el JWT válido, como en el ejemplo siguiente.

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

Cuerpo de respuesta

La solicitud de inicio de sesión produce el siguiente cuerpo de respuesta, que incluye el token de credenciales de Tableau.

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

Después de generar el token de credenciales de Tableau, agregue el token de acceso de Tableau al encabezado de todas las solicitudes posteriores de la API de REST.

Encabezado

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

Todas las solicitudes posteriores de la API de REST que usan el token de acceso de Tableau quedan delimitadas por los ámbitos en el JWT.

Métodos de la API de REST que admiten la autorización JWT

Los siguientes ámbitos se pueden asociar con la aplicación conectada para definir el acceso y los métodos que su aplicación personalizada puede tener para la API de REST(El enlace se abre en una ventana nueva) en nombre de los usuarios.

Notas:

• Para otras funciones de la API de REST que no se enumeran en la siguiente tabla, puede utilizar otros mecanismos de autorización para acceder a los métodos. Para obtener más información, consulte Métodos de autenticación(El enlace se abre en una ventana nueva) en la documentación de la API de REST de Tableau Server.
• Para los alcances compatibles con la API de inserción v3, consulte uno de los siguientes:
  • Configure las aplicaciones conectadas de Tableau para habilitar el inicio de sesión único para el contenido incrustado Configure las aplicaciones conectadas de Tableau para habilitar el inicio de sesión único para el contenido incrustado
  • Registre EAS para habilitar SSO para contenido insertado

Solucionar problemas de alcances

401001: error de inicio de sesión

Si encuentra el error 401001, el cuerpo de la respuesta de inicio de sesión se adjunta con uno de los siguientes códigos de error adicionales específicos de las aplicaciones conectadas: 16, 10084 o 10085.

Por ejemplo, en el siguiente cuerpo de respuesta, "10084" es el código de error de las aplicaciones conectadas que puede usar para ayudar a solucionar problemas al iniciar sesión en Tableau Server utilizando un JWT para la autorización de la API de REST.

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

Para ayudar a resolver el problema, consulte la descripción del código de error aplicable y sus posibles causas.

• 16: No se pudo encontrar el usuario. Este error puede ocurrir porque se ha indicado un valor de "sub " (nombre de usuario) incorrecto

• 10084: No se pudo analizar el token de acceso. Este error puede ocurrir por las siguientes razones:

  • El JWT no es válido o se produjo un problema inesperado
  • Se ha especificado un valor de "aud "(audiencia) incorrecto
  • Para la confianza directa, se produjo un problema con la firma del secreto.

• 10085: No se pudo obtener el secreto para verificar la firma del ID del cliente. Este error puede ocurrir por las siguientes razones:

  • Se ha especificado un ID de cliente incorrecto en "iss"
  • Por confianza directa, se ha especificado un valor de "kid" (ID secreto) incorrecto
  • Para en EAS, no se pueden obtener claves de JWKSource

401002: error de acceso no autorizado

Si encuentra el error 401002 y ha confirmado que tiene los permisos adecuados para realizar la solicitud, asegúrese de que el alcance incluido en el JWT sea correcto y coincida con la solicitud que está intentando realizar. Para obtener una lista de puntos finales y alcances admitidos, consulte la sección anterior Métodos de la API de REST que admiten la autorización JWT.