Microsoft Fabric Extensibility Toolkit の認証ガイドライン

この記事では、Microsoft Fabric 拡張性ツールキットのワークロードを構築するときに認証を操作する方法に関するガイドラインを示します。これには、トークンの操作、同意、フロントエンドアプリケーションからのさまざまなサービスへのアクセスに関する情報が含まれます。

開始する前に、「認証の概要」の概念を理解していることを確認してください。

フロントエンドのみの認証モデル

Extensibility Toolkit は、従来のワークロードと比較して認証を簡略化するフロントエンド専用アーキテクチャを使用します。

直接 API 呼び出し: フロントエンドが Fabric API、Azure サービス、および外部アプリケーションを直接呼び出す
トークンの再利用: 1 つのトークンを使用して、複数の Entra で保護されたサービスに対する認証を行うことができます
簡略化された同意: 同意管理はプラットフォームによって処理され、自動プロンプトが表示されます

Microsoft Entra アプリケーションの構成

[API] タブを公開する

ワークロードアプリケーションのスコープを構成します。

ファブリック統合スコープ: アプリケーション ID を使用して Microsoft Power BI を事前認証する 871c010f-5e61-4fb1-83ac-98610a7e9110
カスタム API スコープ: ワークロードが公開するカスタム API のスコープを追加する
詳細なアクセス許可: 読み取り操作と書き込み操作に異なるスコープを使用する

たとえば、ワークロードでデータ API が公開されている場合は、次のようになります。

読み取り操作のスコープdata.readを追加する
書き込み操作 data.write スコープを追加する
API ハンドラーで適切なスコープを検証する

[API のアクセス許可] タブ

ワークロードがアクセスする必要がある外部サービスのアクセス許可を構成します。

必須: Power BI サービスの Fabric.Extend (Fabric 統合に必須)
Azure サービス: 次のような Azure サービスのスコープを追加する https://storage.azure.com/user_impersonation
カスタムアプリケーション: 独自の Entra で保護されたアプリケーションのスコープを追加する
サードパーティのサービス: Entra 認証をサポートする外部サービスを含める

トークンの使用パターン

複数のサービスにトークンを使用する

Extensibility Toolkit を使用して取得したフロントエンドトークンは、次に対する認証に使用できます。

ファブリック API

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Azure サービス

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

カスタムアプリケーション

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

スコープ管理

Extensibility Toolkit は、一般的なシナリオのスコープ管理を抽象化します。

ファブリッククライアントライブラリ: 必要な Fabric スコープを自動的に含める
Azure クライアントライブラリ: Azure サービススコープを透過的に処理する
カスタムスコープ: 必要に応じて追加のスコープを指定する

同意の管理

初期トークンの取得

まず、認証コンテキストを確立するトークンを取得します。

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

この呼び出しの結果として、次の結果が得られます。

同意プロンプト: ユーザーがアプリケーションに同意していない場合
サイレント取得: 同意が以前に付与された場合

追加のサービスアクセスの処理

ワークロードが追加のサービスにアクセスする必要がある場合は、必要なスコープを指定します。

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

シナリオの例

シナリオ 1: Fabric および Azure サービスへのアクセス

ワークロードには次のことが必要です。

Fabric ワークスペースを一覧表示する
Azure Storage からの読み取り
Azure Key Vault への書き込み

実装:

必要なサービスの API アクセス許可を構成する
初期トークンを取得する
すべてのサービス呼び出しにトークンを使用する
必要に応じて同意プロンプトを処理する

シナリオ 2: カスタムアプリケーション統合

ワークロードは、独自のバックエンドサービスと統合されます。

バックエンドを構成する: Entra トークンを受け入れることを確認する
API アクセス許可の追加: ワークロードアプリケーションにバックエンドのスコープを含める
標準認証を使用する: 同じトークンパターンがカスタムサービスに対して機能する

シナリオ 3: サードパーティのサービス統合

外部の Entra 対応サービスとの統合:

サービスの登録: サードパーティのサービスにワークロードを登録する
スコープの構成: サービスのスコープを API アクセス許可に追加する
トークンの使用: 外部サービスに対して同じ認証パターンを使用する

エラー処理とトラブルシューティング

一般的な認証エラー

同意が必要: ユーザーが特定のスコープに対するアクセス許可を付与していない
条件付きアクセス: 追加の認証要件 (MFA など)
トークンの有効期限: トークンの有効期限が切れ、更新が必要です
無効なスコープ: 要求されたスコープが構成されていないか、使用できません

エラー処理パターン

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

リダイレクト URI の処理

拡張ツールキットには、認証同意ポップアップのリダイレクト URI 処理が組み込まれています。これはメイン index.ts ファイルに実装され、同意のリダイレクトを自動的に処理します。

ツールキットは次の処理を行います。

ウィンドウの自動終了: ユーザーの操作後に同意ポップアップが自動的に閉じる
エラー処理: 特定のエラーコードが検出され、適切に処理されます
エラー表示: 同意の試行に失敗すると、わかりやすいエラーメッセージが表示される

ツールキットの現在の実装:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

注

リダイレクト URI の処理は、拡張ツールキットテンプレートに自動的に含まれます。エラー処理の動作をカスタマイズする場合を除き、これを自分で実装する必要はありません。

ベストプラクティス

トークン管理

キャッシュトークン: 有効期限が切れるまでトークンを再利用する
更新の処理: トークンの自動更新ロジックを実装する
セキュリティで保護されたストレージ: トークンをブラウザーのメモリに安全に格納する

最小限のアクセス許可: 実際に必要なスコープのみを要求する
プログレッシブ同意: 機能の使用に応じて追加のアクセス許可を要求する
クリアメッセージング: アクセス許可が必要な理由をユーザーに説明する

エラー処理

優雅な劣化: 可能な場合はフォールバック機能を提供する
ユーザーフィードバック: 認証要件を明確に伝える
再試行ロジック: 一時的な障害に対して適切な再試行メカニズムを実装する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-15