次の方法で共有

認証JavaScript API参照

Fabric Extensibility Toolkitは、Fabric API、Azureサービス、そしてEntraで保護されたあらゆるアプリケーションにアクセスするための認証トークンを取得するためのJavaScript APIを提供します。 この記事では、包括的なAPIリファレンスと利用例を提供します。

ヒント

簡単な入門ガイドは「 Microsoft Entraトークンの取得」をご覧ください。

API リファレンス

acquireFrontendAccessToken(params: AcquireFrontendAccessTokenParams): Promise<AccessToken>;

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

注

現在の拡張性ツールキットの実装は、基本的なトークン取得をスコープでサポートしています。 完全な同意プロンプトや条件付きアクセス処理などの高度な機能はまだ利用できませんが、今後のリリースで追加される可能性があります。

APIは以下を含む AccessToken オブジェクトを返します:

  • トークン:Authorizationヘッダーで使用するJWTトークン文字列

基本的な使用方法

単純なトークン取得

// Acquire a token with default Fabric permissions
const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

// Use the token in API calls
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/json'
  }
});

特定のスコープを持つトークン

// Request specific scopes for Azure Storage
const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: ['https://storage.azure.com/user_impersonation']
});

トークン使用例

ファブリックAPIアクセス

トークンはFabric REST APIと直接連携して使用できます:

async function listWorkspaces() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });
  
  const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Azure service access

アクセスが必要なAzureサービスを指定するためにスコープを使います:

async function readFromStorage(accountName, containerName, blobName) {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token.token}`,
      'x-ms-version': '2021-12-02'
    }
  });
  
  return await response.text();
}

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

自分のEntraで保護されたアプリケーションにアクセスしてください:

async function callCustomAPI() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://myapp.contoso.com/data.read']
  });
  
  const response = await fetch('https://myapp.contoso.com/api/data', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

パラメーター リファレンス

scopes

トークンに必要な権限を指定するスコープ文字列の配列です。

一般的なAzureサービススコープ:

  • https://storage.azure.com/user_impersonation - Azure Storage
  • https://vault.azure.net/user_impersonation - Azure Key Vault
  • https://management.azure.com/user_impersonation - Azure Resource Manager
  • https://graph.microsoft.com/User.Read - マイクロソフトグラフ

使用例:

const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: [
    'https://storage.azure.com/user_impersonation'
  ]
});

空のスコープ配列: デフォルトのFabric権限を持つトークンを取得するには、空の配列を使用します:

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

拡張性ツールキットは、同意のワークフローを自動的に処理します:

  • 初回要請:同意が欠落した場合、ポップアップウィンドウが表示されます
  • ユーザー操作:ユーザーが権限を付与または拒否します
  • 自動閉鎖:ユーザーの操作後にポップアップが自動的に閉じます
  • トークン配信:成功した場合、トークンはアプリケーションに返されます

ツールキットは同意のポップアップを自動的に管理しますが、リダイレクトURIの動作をカスタマイズできます。 同意応答を処理するリダイレクトページを作成しましょう:

// redirect.js - Handle consent redirect
const redirectUriPath = '/close';
const url = new URL(window.location.href);

if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle consent errors
  if (url?.hash?.includes("error")) {
    // Extract error information
    const errorMatch = url.hash.match(/error=([^&]+)/);
    const errorDescription = url.hash.match(/error_description=([^&]+)/);
    
    // Handle specific errors
    if (url.hash.includes("AADSTS650052")) {
      console.error("Service principal not configured");
    } else if (url.hash.includes("AADSTS65004")) {
      console.error("User declined consent");
    }
  }
  
  // Always close the popup immediately
  window.close();
}

異なるテナント間でのリソースアクセス:

// Request consent for cross-tenant access
const token = await workloadClient.auth.acquireAccessToken({
  additionalScopesToConsent: ['https://api.partner-app.com/data.read']
});

エラー処理

一般的なエラー シナリオ

async function robustTokenAcquisition() {
  try {
    return await workloadClient.auth.acquireAccessToken();
  } catch (error) {
    switch (error.code) {
      case 'user_cancelled':
        console.log('User cancelled the consent dialog');
        break;
      case 'consent_required':
        console.log('Additional consent required');
        break;
      case 'interaction_required':
        console.log('User interaction required');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
    throw error;
  }
}

トークンの有効期限処理

class TokenManager {
  private currentToken: AccessToken | null = null;
  
  async getValidToken(): Promise<AccessToken> {
    if (!this.currentToken || this.isTokenExpired(this.currentToken)) {
      this.currentToken = await workloadClient.auth.acquireAccessToken();
    }
    return this.currentToken;
  }
  
  private isTokenExpired(token: AccessToken): boolean {
    // Add buffer time to prevent requests with almost-expired tokens
    const bufferMinutes = 5;
    const expirationWithBuffer = new Date(token.expiresOn.getTime() - (bufferMinutes * 60 * 1000));
    return new Date() >= expirationWithBuffer;
  }
}

ベスト プラクティス

トークンキャッシュと再利用

  • キャッシュトークン:トークンを有効期限までメモリに保存します
  • 自動更新:有効期限前に自動トークン更新を実装します
  • セキュアストレージ:トークンをローカルストレージやクッキーに永続化しないでください

スコープ管理

  • 最小限のスコープ:必要な権限のみを要求してください
  • プログレッシブコンセント:機能使用に応じて追加範囲を要求
  • スコープ検証:API呼び出し前にトークンに必要なスコープを含めることを検証します

高度なエラー処理

  • グレースフル・デグレード:認証が失敗した際にフォールバック機能を提供します
  • ユーザーメッセージング:なぜ権限が必要なのかを明確に説明してください
  • 再試行ロジック: 一時的な障害に対して適切な再試行メカニズムを実装する

パフォーマンスの最適化

  • 並列リクエスト:可能な限り複数のサービスのトークンを並列取得します
  • バッチ操作:トークン取得のオーバーヘッドを最小限に抑えるためのAPI呼び出しをグループ化します
  • キャッシュ管理:効率的なトークンキャッシュ戦略を実装する

関連コンテンツ

  • Last updated on