次の方法で共有

Microsoft Fabric のワークロード認証ガイドラインの概要

  • [アーティクル]

この記事では、Microsoft Fabric ワークロードを構築するときに認証を操作する方法に関するガイドラインを示します。 これには、トークンと同意の操作に関する情報が含まれています。

開始する前に、認証の概要 と認証のセットアップの概念を理解していることを確認してください。

データ プレーン API とコントロール プレーン API

  • データ プレーン API は、ワークロード バックエンドが公開する API です。 ワークロード フロントエンドは、それらを直接呼び出すことができます。 データ プレーン API では、どの API を公開するかをワークロード バックエンドが決定できます。

  • コントロール プレーン API は、ファブリックを経由する API です。 このプロセスは、JavaScript API を呼び出すワークロード フロントエンドから始まり、Fabric がワークロード バックエンドを呼び出すことで終了します。 このような API の例として、項目の作成があります。

    コントロール プレーン API の場合、ワークロードはワークロード バックエンドで定義されているコントラクトに従い、それらの API を実装する必要があります。

Microsoft Entra ID でワークロードのアプリケーションの [API] タブを公開する

[API の公開] タブで、コントロール プレーン API のスコープとデータ プレーン API のスコープを追加する必要があります。

  • コントロール プレーン API 用に追加されたスコープは、アプリケーション ID d2450708-699c-41e3-8077-b0c8341509aaを使用して Fabric Client for Workloads アプリケーションを事前認証する必要があります。 これらのスコープは、Fabric が呼び出したときにワークロード バックエンドが受け取るトークンに含まれます。

    フローを機能させるには、コントロール プレーン API のスコープを少なくとも 1 つ追加する必要があります。

  • データ プレーン API 用に追加されたスコープは、アプリケーション ID 871c010f-5e61-4fb1-83ac-98610a7e9110を使用して Microsoft Power BI を事前認証する必要があります。 これらは、acquireAccessToken JavaScript API が返すトークンに含まれています。

    データ プレーン API の場合、このタブを使用して、ワークロードが公開する各 API の詳細なアクセス許可を管理できます。 理想的には、ワークロード バックエンドが公開する API ごとに一連のスコープを追加し、クライアントから API が呼び出されたときに、受信したトークンにそれらのスコープが含まれていることを検証する必要があります。 例えば：

    • ワークロードは、クライアントに 2 つの API (ReadData と WriteData) を公開します。
    • ワークロードは、data.read と data.writeの 2 つのデータ プレーン スコープを公開します。
    • ReadData API では、ワークロードは、フローを続行する前に、data.read スコープがトークンに含まれていることを検証します。 同じことが WriteDataにも当てはまります。

Microsoft Entra ID のワークロードのアプリケーションの [API アクセス許可] タブ

[API のアクセス許可] タブで、ワークロードがトークンを交換するために必要なすべてのスコープを追加する必要があります。 Power BI サービスの下に追加する必須のスコープは Fabric.Extend です。 Fabric への要求は、このスコープなしで失敗する可能性があります。

トークンと同意の操作

データ プレーン API を使用する場合、ワークロード フロントエンドは、ワークロード バックエンドへの呼び出し用のトークンを取得する必要があります。

次のセクションでは、ワークロード フロントエンドが JavaScript API と on-behalf-of (OBO) フローを使用して、ワークロードと外部サービスのトークンを取得し、同意を処理する方法について説明します。

手順 1: トークンを取得する

ワークロードは、パラメーターを指定せずに JavaScript API を使用してトークンを要求することから始まります。 この呼び出しでは、次の 2 つのシナリオが発生する可能性があります。

  • ユーザーには、ワークロードが構成したすべての静的依存関係 (API のアクセス許可 タブで構成されているもの) の同意ウィンドウが表示されます。 このシナリオは、ユーザーがアプリケーションのホーム テナントの一部ではなく、以前にこのアプリケーションに対して Microsoft Graph に同意しなかった場合に発生します。

  • ユーザーに同意ウィンドウが表示されません。 このシナリオは、ユーザーがこのアプリケーションに対して Microsoft Graph に少なくとも 1 回同意した場合、またはユーザーがアプリケーションのホーム テナントの一部である場合に発生します。

どちらのシナリオでも、ワークロードでは、ユーザーがすべての依存関係に対して完全な同意を与えたかどうかは気にしないでください (現時点ではわかりません)。 受信したトークンにはワークロード バックエンドの対象ユーザーが含まれており、ワークロード フロントエンドからワークロード バックエンドを直接呼び出すために使用できます。

手順 2: 外部サービスにアクセスする

ワークロードは、認証を必要とするサービスにアクセスする必要がある場合があります。 そのアクセスには、OBO フローを実行する必要があります。ここで、クライアントまたは Fabric から受け取ったトークンを別のサービスに交換します。 同意がない、またはワークロードがトークンを交換しようとしているリソースで構成されている Microsoft Entra 条件付きアクセス ポリシーが原因で、トークン交換が失敗する可能性があります。

この問題を解決するには、フロントエンドとバックエンドの間で直接呼び出しを行う場合には、ワークロードがエラーをクライアントに伝達する必要があります。 ワークロードは、Fabricの呼び出しを操作する際、ワークロード通信で説明されているエラー伝達方法を使用して、エラーを クライアントに伝達する責任があります。

ワークロードがエラーを伝達した後、acquireAccessToken JavaScript API を呼び出して同意または条件付きアクセス ポリシーの問題を解決し、操作を再試行できます。

データ プレーン API の障害については、「多要素認証、条件付きアクセス、増分同意の処理」を参照してください。 コントロール プレーン API の障害については、ワークロード通信に関するページを参照してください。

シナリオの例

3 つの Fabric API にアクセスする必要があるワークロードを見てみましょう。

  • ワークスペースの一覧表示: GET https://api.fabric.microsoft.com/v1/workspaces

  • ウェアハウスの作成: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • レイクハウスファイルに書き込む: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

これらの API を使用できるようにするには、ワークロード バックエンドで次のスコープのトークンを交換する必要があります。

  • ワークスペースを一覧表示する場合: https://analysis.windows.net/powerbi/api/Workspace.Read.All または https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
  • 倉庫を作成する場合: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All または https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • lakehouse ファイルに書き込む場合: https://storage.azure.com/user_impersonation

Note

各 Fabric API に必要なスコープについては、このリファレンス記事参照してください。

前述のスコープは、API のアクセス許可でワークロード アプリケーションで構成する必要があります。

ワークロードで発生する可能性があるシナリオの例を見てみましょう。

例 1

ワークロード バックエンドに、ユーザーのワークスペースを取得してクライアントに返すデータ プレーン API があるとします。

  1. ワークロード フロントエンドは、JavaScript API を使用してトークンを要求します。

  2. ワークロード フロントエンドは、ワークロード バックエンド API を呼び出してユーザーのワークスペースを取得し、要求にトークンをアタッチします。

  3. ワークロード バックエンドはトークンを検証し、必要なスコープと交換しようとします (たとえば https://analysis.windows.net/powerbi/api/Workspace.Read.All)。

  4. ユーザーがこのリソースにアクセスするためにアプリケーションに同意しなかったため、ワークロードは指定されたリソースのトークンを交換できません (AADSTS エラー コード参照)。

  5. ワークロード バックエンドは、そのリソースに同意する必要があることを指定して、ワークロード フロントエンドにエラーを伝達します。 ワークロード フロントエンドは、acquireAccessToken JavaScript API を呼び出し、additionalScopesToConsentを提供します。

    workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

    または、ワークロードは、アプリケーションで構成されているすべての静的依存関係に同意を求めることもできるため、JavaScript API が呼び出され、promptFullConsentが提供されます。

    [https://login.microsoftonline.com/consumers/](workloadClient.auth.acquireAccessToken({promptFullConsent: true}))

この呼び出しでは、ユーザーが依存関係の一部に同意したかどうかに関係なく、同意ウィンドウが表示されます。 その後、ワークロード フロントエンドは操作を再試行できます。

Note

同意エラーが発生してもトークン交換が失敗する場合は、ユーザーが同意を付与しなかったことを意味します。 ワークロードでは、このようなシナリオを処理する必要があります。たとえば、この API には同意が必要であり、それなしでは機能しないことをユーザーに通知します。

例 2

ワークロード バックエンドが Create Item API で OneLake にアクセスする必要があるとします (Fabric からワークロードへの呼び出し)。

  1. ワークロード フロントエンドは、Create Item JavaScript API を呼び出します。

  2. ワークロード バックエンドは Fabric から呼び出しを受け取り、委任されたトークンを抽出して検証します。

  3. ワークロードはトークンを と交換しようとしますが、Azure Storage にアクセスするためにユーザー構成の多要素認証のテナント管理者が必要であるために失敗します (AADSTS エラー コード参照)。

  4. ワークロードは、「ワークロード通信で説明されているエラー伝達を使用して、Microsoft Entra ID からクライアントにエラーで返された要求と共にエラー 伝達します。

  5. ワークロード フロントエンドは、acquireAccessToken JavaScript API を呼び出し、要求を claimsForConditionalAccessPolicyとして提供します。ここで、claims はワークロード バックエンドから伝達された要求を参照します。

    workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

その後、ワークロードは操作を再試行できます。

同意要求の際のエラーの処理

さまざまなエラーが原因で、ユーザーが同意を与えることができない場合があります。 同意要求の後、応答はリダイレクト URI に返されます。 この例では、このコードが応答を処理します。 (index.ts ファイルで見つけることができます)。

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

ワークロード フロントエンドは、URL からエラー コードを抽出し、それに応じて処理できます。

Note

どちらのシナリオ (エラーと成功) でも、ワークロードは常に待機時間なしでウィンドウを直ちに閉じる必要があります。