Authentication API を使用すると、ビジュアルはサインインしているユーザーの Microsoft Entra ID (旧称 Azure AD) アクセス トークンを取得でき、シングル サインオン認証が容易になります。
Power BI 管理者は、 グローバル スイッチを使用して API を有効または無効にすることができます。 既定の設定では、API がブロック (無効) されます。
この API は AppSource ビジュアルにのみ適用され、プライベート ビジュアルには適用されません。 開発中のビジュアルは、公開前にデバッグ モードでテストできます。
サポートされている環境
次の環境がサポートされています。
- Web
- デスクトップ
- RS Desktop
- モバイル
サポートされていない環境
次の環境はまだサポートされていません。
- RS サービス
- 埋め込み分析
- 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: トークンの取得に関連付けられている次のいずれかの特権状態を返します。
- 許可: 現在の環境で権限が許可されます。
- NotDeclared: 特権宣言がビジュアル機能セクションにありません。
- NotSupported: 現在の環境では、特権はサポートされていません。
- DisabledByAdmin: ファブリック管理者が特権の使用を拒否しました。
次のサンプル コードは、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
考慮事項と制限事項
次のいずれかの条件が適用される場合、トークンの取得はブロックされます。
テナント スイッチがオフになっています。
ユーザーが (デスクトップで) サインインしていません。
ISV は Power BI アプリケーションを事前認証しませんでした。
AADAuthentication 特権パラメーターの形式が無効です。
ビジュアルが パブリックに承認されていない か、デバッグ ビジュアルではありません。
ビジュアルによって対象ユーザーとして構成されたビジュアルのバックエンド サービスには、ビジュアルを使用するコンシューマー テナントの Graph API に対する適切な同意がありません。 同意の詳細については、 テナント管理者の同意に関するページを参照してください。