次の方法で共有

Microsoft Fabric でのワークロード認証に関するガイドラインの概要

  • [アーティクル]

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

開始する前に、必ず「認証の概要」と「認証のセットアップ」で説明している概念を十分に理解しておいてください。

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

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

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

    コントロール プレーン 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) がクライアントに公開されます。
    • ワークロードによって、2 つのデータ プレーン スコープ (data.read と data.write) が公開されます。
    • 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
  • レイクハウス ファイルに書き込む場合: 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 (Fabric からワークロードへの呼び出し) で OneLake にアクセスする必要があるとします。

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

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

  3. ワークロードは https://storage.azure.com/user_impersonation のトークンを交換しようとしますが、ユーザーが構成した多要素認証のテナント管理者が 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

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