接続済みアプリのアクセス スコープ
REST API へのアクセスを連携アプリを使用して承認することにより、次を実現します。
- セキュリティの強化 — コンテナ内で .env ファイルを介して管理者ユーザーのパスワードを保存および管理するよりも、JWT をベアラー トークンとして使用する方が本質的に安全です
- 効率の向上 — JWT をベアラー トークンとして使用すると、2 つのリクエストではなく、サインイン エンドポイントへの 1 つのリクエストで偽装を簡単化することができます
- 動的なコンテンツ検索や高度なフィルタリングなど、複雑な Tableau 統合とバックエンド クエリを拡張および自動化します
スコープ アクション
接続済みアプリが使用するスコープは、JWT 認可をサポートする REST API メソッド (下記) を通じて、コンテンツや管理アクションへのアクセス権を付与します。スコープはコロンで区切られた文字列であり、名前空間 tableau で始まり、アクセスが許可されている Tableau リソース (datasources など) が続き、そのリソースに対して許可されているアクション (update など) で終わります。
スコープが実行できるアクションは次のとおりです。
createreadrunupdatedownloaddelete
たとえば、カスタム アプリケーションが データ ソースの更新(新しいウィンドウでリンクが開く)メソッドを呼び出せるようにするスコープは、tableau:datasources:update のようになります。
スコープの種類
使用するスコープの種類は、有効にするコンテンツまたは管理アクションによって異なります。スコープは通常、コンテンツ読み取り、個別、ワイルドカード、クロスカテゴリのいずれかのタイプに分類されます。
コンテンツ読み取りスコープ: コンテンツ読み取りスコープ
tableau:content:readは、Tableau コンテンツに対してサポートされている GET メソッドを有効にします。このスコープを使用すると、REST API カテゴリ全体でアクションを有効にできます。具体的には、このスコープを使用して、データ ソース、メトリクス、ビュー、ワークブック、プロジェクト、およびサイトに対する GET メソッドを有効にします。注: ユーザーやグループなどの管理アクションに対する GET メソッドを有効にするには、それらの個別スコープを使用できます。
個別スコープ: サポートされているコンテンツと管理アクションを有効にするには、それらの個別スコープを使用できます。個別スコープは、通常、単一のメソッドと REST API カテゴリに関連付けられています。
例:
- データ ソース アクションのパブリッシュまたは更新を有効にする場合は、それぞれ個別スコープ
tableau:datasources:createまたはtableau:datasources:updateを使用できます。 - ユーザーの追加または削除などの管理アクションについては、それぞれ個別スコープ
tableau:users:createまたはtableau:users:deleteを使用できます。
注: REST API のカテゴリをまたがるアクションを有効にできる個別スコープもいくつかあります。例えば、
tableau:views:downloadは、データの表示やワークブックの REST API カテゴリでアクションを有効にします。- データ ソース アクションのパブリッシュまたは更新を有効にする場合は、それぞれ個別スコープ
ワイルドカード (*) スコープ: 特定のスコープでは、アクションをワイルドカード文字 (*) に置き換えて、特定の REST API カテゴリ内でサポートされているアクションを有効にすることができます。
例:
- ワイルドカード スコープ
tableau:projects:*を使用すると、プロジェクトの REST API カテゴリで create、delete、および update アクションを有効にできます。 - ワイルドカード スコープ
tableau:users:*を使用すると、ユーザーの REST API カテゴリで get/list、add、delete、および update アクションを有効にできます。 - ワイルドカード スコープ
tableau:tasks:*を使用すると、抽出とサブスクプションの REST API カテゴリで get/list、add、delete、update、および run アクションを有効にできます。また、このスコープは、データ ソースの更新 (抽出の場合) とワークブックの更新を有効にします。
- ワイルドカード スコープ
クロスカテゴリ スコープ: コンテンツ読み取りスコープに加えて、使用された場合、さまざまな REST API カテゴリにまたがってサポートされているアクションを有効にする追加スコープがいくつかあります。
例:
tableau:tasks:runスコープを使用すると、データ ソースとワークブックの REST API カテゴリでアクションを有効にします。- 繰り返しになりますが、
tableau:views:downloadスコープを使用すると、データの表示とワークブックの REST API カテゴリでアクションを有効にします。 tableau:permissions:updateまたはtableau:permissions:deleteなどのパブリッシュ スコープを使用すると、データ ソース、ワークブック、およびプロジェクトの REST API カテゴリでアクションを有効にします。
REST API アクセスを認可する方法の概要
次のリストは、JWT を介して REST API へのアクセスをリクエストする手順をまとめたものです。
- 次のいずれかの方法を使用して、連携アプリを作成します。
- 有効な JWT を生成します。カスタム アプリケーションは、指定したスコープで設定された有効な JWT を実行時に生成します
- サインイン(新しいウィンドウでリンクが開く) リクエストを行います。カスタム アプリケーションは、JWT を使用してサインインをリクエストし、Tableau 認証資格情報トークンとサイトID (LUID) を返します。
- 後続のリクエストで Tableau アクセス トークンを使用します。後続の REST API 呼び出しでは、1) Tableau 認証資格情報トークンを
X-Tableau-Auth(新しいウィンドウでリンクが開く) ヘッダー値として使用し、2) サイト ID (LUID) をリクエスト URI で使用します。
例
直接信頼を使用して連携アプリを作成する場合の例です。直接信頼を使用して REST API を呼び出すカスタム アプリケーションは、連携アプリが生成したクライアント ID とクライアント シークレットを使用して有効な JWT を生成します。
JWT のスコープ
REST API へのアクセスを正常に認可するには、JWT に REST API 機能を定義するスコープが含まれている必要もあります。たとえば、データ ソース関連のさまざまなメソッドを有効にするには、JWT に次のようなスコープを含めることができます。
"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"
または
"tableau:content:read","tableau:datasources:*","tableau:tasks:run"
注: スコープの値はリスト型として渡す必要があります。
サインイン リクエストの URI
REST API を呼び出すには、カスタム アプリケーションは最初にサインイン要求を行い、Tableau 認証資格情報のトークンを生成する必要があります。
POST https://myco/api/3.17/auth/signinリクエスト本文
JWT を使用して REST API へのアクセスを認可するには、サインイン リクエストの本文に次の例のような有効な JWT が含まれている必要があります。
<tsRequest>
<credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
<site contentUrl="mycodotcom"/>
</credentials>
</tsRequest>レスポンス本文
サインイン リクエストに対して、Tableau 認証資格情報トークンを含む、次のようなレスポンス本文が生成されます。
<tsResponse>
<credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
<site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</credentials>
</tsResponse>Tableau アクセス トークンが生成されたら、後続のすべての REST API リクエストのヘッダーに追加します。
ヘッダー
X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd
Tableau アクセス トークンを使用する後続のすべての REST API リクエストは、JWT のスコープによって制限されます。
JWT 認可をサポートする REST API メソッド
接続済みアプリのスコープは、ユーザーに代わって、カスタム アプリケーションに Tableau REST API 機能へのアクセス権を付与します
JWT がサポートするメソッドに必要なスコープは、Tableau REST API(新しいウィンドウでリンクが開く) ヘルプのプロパティ ブロックにあります。スコープがメソッドの properties ブロックにリストされていない場合、そのメソッドへのアクセスを JWT で制御することはできません。
たとえば、Tableau REST API で クエリ サイト(新しいウィンドウでリンクが開く) メソッドを呼び出せるようにするスコープは、tableau:sites:read のようになります。
注:
- サインイン(新しいウィンドウでリンクが開く)とサインアウト(新しいウィンドウでリンクが開く)のメソッドは、共に JWT 認証でサポートされていますが、
- 埋め込み API v3 でサポートされているスコープについては、次のいずれかを参照してください。
ワイルドカード (*) スコープについて
ワイルドカード スコープは、特定のアクションではなく、ワイルドカード文字 (*) を使用して、特定の Tableau REST API カテゴリ内でサポートされている複数のアクションを有効にします。
例
| スコープ | 有効にされるメソッド |
|---|---|
tableau:datasources:* | データ ソースの create、update、および update connection メソッドを有効にします。 |
tableau:metrics:* | メトリクスの query、update、および delete アクションを有効にします。 |
tableau:workbooks:* | ワークブックの publish、update、download、および preview image アクションを有効にします。 |
tableau:groups:* | グループの create、query、update、および delete アクションを有効にします。 |
tableau:projects:* | プロジェクトの create、delete、update メソッドを有効にします。 |
tableau:users:* | ユーザーの get/list、add、delete、および update メソッドを有効にします。 |
tableau:tasks:*注: このスコープもクロスカテゴリです。 | 抽出タスクとサブスクリプション タスクの get/list、add、delete、update、および run メソッドを有効にします。 ワークブックのデータ ソースの update メソッドを有効にします。 |
クロスカテゴリ スコープについて
クロスカテゴリ スコープは、複数の Tableau REST API カテゴリにまたがってサポートされている複数のアクションを有効にします。
例
| スコープ | 有効にされるメソッド |
|---|---|
tableau:content:read | データ ソース、メトリクス、ビュー、ワークブック、プロジェクト、サイトなど、Tableau コンテンツの read/list メソッドを有効にします。 |
tableau:tasks:run | データ ソース、ワークブック、抽出の run メソッドを有効にします。 |
tableau:views:download | データの表示とワークブックの download メソッドを有効にします。 |
tableau:tasks:*注: このスコープもワイルドカードです。 | 抽出タスクとサブスクリプション タスクの get/list、add、delete、update、および run メソッドを有効にします。 ワークブックのデータ ソースの update メソッドを有効にします。 |
トラブルシューティングのスコープ
401001 - サインイン エラー
エラー 401001 が発生した場合、サインインの応答本文には、追加の接続アプリ固有のエラー コード (16、10084、または 10085) のいずれかが追加されます。
たとえば、次の応答本文では、「10084」は接続アプリのエラー コードであり、REST API 認証に JWT を使用して Tableau Server にサインインする際に起こる問題のトラブルシューティングに役立ちます。
<error code="401001"> "summary": "Signin Error", "detail": "Error signing in to Tableau Cloud (10084)" </error>
問題を解決するには、該当するエラー コードとその潜在的な原因の説明を参照してください。
16: Cloud でユーザーが見つかりません - このエラーは、正しくない「
sub」 (ユーザー名) が指定されると発生する可能性があります。
10084: Cloud でアクセス トークンを解析できませんでした - このエラーは、次の理由で発生する可能性があります。
- JWT が無効であるか、予期しない問題が発生しました
- 正しくない [
aud] (オーディエンス) が指定されました - 直接信頼の場合、シークレットの署名に問題がありました
10085: Cloud でクライアント ID の署名を検証するためのシークレットを取得できませんでした - このエラーは、次の理由で発生する可能性があります。
- 指定された [
iss] のクライアント ID が正しくありません - 直接信頼の場合、正しくない [
kid] (シークレット ID) が指定されました -
- 指定された [
401002 - 不正アクセス エラー
エラー 401002 が発生し、リクエストを行う適切なパーミッションがあることを確認した場合は、JWT に含まれるスコープが正しく、作成しようとしているリクエストと一致していることを確認してください。エンドポイントとサポートされるスコープのリストについては、上記の「JWT 認可をサポートする REST API メソッド」セクションを参照してください。