次の方法で共有

認証 API

  • [アーティクル]

認証 API を使うと、サインインしているユーザーの Microsoft Entra ID (旧称 Azure AD) アクセス トークンを視覚エフェクトで取得できるので、シングル サインオン認証が容易になります。

Power BI 管理者は、グローバル スイッチを使って API を有効または無効にすることができます。 既定の設定では、この API はブロックされます (無効です)。

この API を適用できるのは AppSource 視覚エフェクトのみであり、プライベート視覚エフェクトには適用できません。 開発中の視覚エフェクトを公開する前にデバッグ モードでテストできます。

サポートされる環境

次の環境がサポートされています。

  • Web
  • デスクトップ
  • RS Desktop
  • 携帯電話

サポートされていない環境

次の環境はまだサポートされていません。

  • RS Service
  • 埋め込み分析
  • Teams

認証 API の使用方法

capabilities.json ファイルの中で、Microsoft Entra ID が登録済みのアプリケーション URI を使って、サポートされる各クラウド向けに "AADAuthentication" 特権を追加します。 Fabric は、現在のクラウド用に構成された対象ユーザーに照らしてトークンを生成し、それをビジュアルに配信します。
これでビジュアルはトークンを利用して、各バックエンド サービスごとのユーザーに対して認証が行なえるようになります。

"privileges": [
    {
        "name": "AADAuthentication",
        "parameters": {
            "COM": "https://contoso.com",
            "CN": "https://contoso.cn"
        }
    }
]

pbiviz.json ファイルで、API バージョンを 5.9.1 以上に設定します。

新しく公開された AcquireAADTokenService には 2 つのメソッドがあります。

  • acquireAADToken: ビジュアルの型が AcquireAADTokenResult の認証トークン ペイロードを返します。または、これをフェッチできない場合は null を返します。

     /**
 * Enum representing the various clouds supported by the Authentication API.
 */
export const enum CloudName {
    COM = "COM",         // Commercial Cloud
    CN = "CN",           // China Cloud
    GCC = "GCC",         // US Government Community Cloud
    GCCHIGH = "GCCHIGH", // US Government Community Cloud High
    DOD = "DOD",         // US Department of Defense Cloud
}

/**
 * Interface representing information about the user associated with the token.
 */
export interface AcquireAADTokenUserInfo {
    userId?: string;   // Unique identifier for the user
    tenantId?: string; // Unique identifier for the tenant
}

/**
 * Interface representing information about the fabric environment.
 */
export interface AcquireAADTokenFabricInfo {
    cloudName?: CloudName; // Name of the cloud environment
}

/**
 * Interface representing the result of acquiring a Microsoft Entra ID token.
 */
export interface AcquireAADTokenResult {
    accessToken?: string;       // Access token issued by Microsoft Entra ID
    expiresOn?: number;         // Expiration time of the access token
    userInfo?: AcquireAADTokenUserInfo;     // Information about the user associated with the token
    fabricInfo?: AcquireAADTokenFabricInfo; // Information about the fabric environment
}

  • acquireAADTokenstatus: トークンの取得に関連付けられた次の特権状態のいずれかを返します。

    • Allowed: 現在の環境で特権が許可されています。
    • NotDeclared: 視覚エフェクトの機能セクションに特権の宣言がありません。
    • NotSupported: この特権は現在の環境ではサポートされていません。
    • DisabledByAdmin: Fabric 管理者が特権の使用を拒否しました。

次のサンプル コードは、API を使って Microsoft Entra ID トークンを取得する方法を示しています。

    // Step 1: Check the status of AAD token acquisition 
    const acquireTokenStatus = await this.acquireAADTokenService.acquireAADTokenStatus(); 

    // Step 2: Verify if acquiring the token is allowed 
    if (acquireTokenStatus === PrivilegeStatus.Allowed) { 

   // Step 3: Acquire the Microsoft Entra ID token
   const acquireAADTokenResult: AcquireAADTokenResult = await this.acquireAADTokenService.acquireAADToken(); 

   // Step 4: Confirm successful acquisition of the access token
   if (acquireAADTokenResult.accessToken) { 

            // Step 5: Call your backend API with the obtained token 
        } 
    } 

    // Step 6: Handle unsuccessful AAD token acquisition

考慮事項と制限事項

次の条件のいずれかが該当する場合、トークンの取得はブロックされます。

  • テナント スイッチがオフになっています。

  • ユーザーが (Desktop に) サインインしていません。

  • ISV は Power BI アプリケーションを事前に認可していません。

  • AADAuthentication 特権パラメーターの形式が無効です。

  • この視覚エフェクトはパブリックに承認されていないか、デバッグ視覚エフェクトではありません。

  • 視覚エフェクトのバックエンド サービスが、視覚エフェクトによって対象ユーザーとして構成されており、視覚エフェクトを使うコンシューマー テナントの Graph API に対して適切な同意を得ていません。 同意の詳細については、テナント管理者の同意、を参照してください。

関連するコンテンツ

Microsoft Entra ID アプリケーションのセットアップ