使用OAuth2.0集成Tableau嵌入代码时JWT登录API报错排查

我们尝试通过带OAuth 2.0信任的Connected Apps将Tableau仪表板集成至自有网站，已在Tableau中创建Connected App并获取Client ID、Site ID等信息，按官方文档生成JWT令牌后，调用以下登录API：

curl --location '{server-url}/api/3.20/auth/signin' \
--header 'Content-Type: application/xml' \
--data '<tsRequest>
    <credentials jwt="{jwt-token}">
        <site contentUrl="{content-url}"/>
    </credentials>
</tsRequest>'

返回401001错误：

<?xml version='1.0' encoding='UTF-8'?>
<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api https://help.tableau.com/samples/en-us/rest_api/ts-api_3_20.xsd">
    <error code="401001">
        <summary>Signin Error</summary>
        <detail>Error signing in to Tableau Server</detail>
    </error>
</tsResponse>

以下是针对JWT令牌的排查要点：

• 校验签名算法匹配：Tableau Connected App默认要求使用RS256算法，确认生成JWT时使用的是创建App时下载的RSA私钥，签名算法未误用HS256等其他类型。可通过解码JWT查看header中的alg字段是否为RS256。
• 核对JWT声明的正确性：
  • iss必须严格等于Connected App的Client ID
  • sub需为Tableau中存在的有效用户ID/用户名，且该用户拥有目标站点的访问权限
  • aud要匹配Tableau服务器受众：Tableau Online填https://online.tableau.com，私有服务器填https://<你的服务器域名>
  • exp（过期时间）必须是未来的时间戳，iat（签发时间）不能晚于当前时间
  • scp声明需包含所需权限，比如至少包含tableau:views:embed，且权限范围与Connected App配置一致
• 确认Site的ContentUrl无误：请求中的contentUrl是站点的URL后缀（例如Tableau Online站点URL为https://online.tableau.com/#/site/MySite，则contentUrl为MySite），注意区分大小写，且该站点真实存在、用户有权访问。
• 验证JWT完整性：生成的JWT需是完整的Base64URL编码字符串，无多余空格、换行或截断，确保所有声明编码正确未被篡改。
• 检查Connected App信任配置：确认Connected App已启用，信任的受众包含你的服务器域名或Tableau服务器地址，Tableau Online环境下需确保App状态为“已批准”。
• 核对API版本兼容性：使用的API版本（3.20）需与Tableau服务器版本匹配，若服务器版本较低，需降级API版本至兼容范围。

内容的提问来源于stack exchange，提问作者Ajay Patidar