認証 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 に対して適切な同意を得ていません。 同意の詳細については、テナント管理者の同意、を参照してください。