Bagikan melalui

API Autentikasi

  • Artikel

API Autentikasi memungkinkan visual untuk mendapatkan token akses Microsoft Entra ID (sebelumnya dikenal sebagai Azure AD) untuk pengguna yang masuk, memfasilitasi autentikasi akses menyeluruh.

Administrator Power BI dapat mengaktifkan atau menonaktifkan API melalui sakelar global. Pengaturan default memblokir (menonaktifkan) API.

API hanya berlaku untuk visual AppSource, dan bukan untuk visual privat. Visual yang sedang dikembangkan dapat diuji dalam mode debug sebelum diterbitkan.

Lingkungan yang didukung

Lingkungan berikut didukung:

  • Web
  • Desktop
  • RS Desktop
  • Seluler

Lingkungan yang tidak didukung

Lingkungan berikut belum didukung:

  • Layanan RS
  • Analitik tertanam Power BI
  • Teams

Cara menggunakan API Autentikasi

Dalam file capabilities.json, tambahkan hak istimewa "AADAuthentication" dengan URI aplikasi terdaftar ID Microsoft Entra untuk setiap cloud yang didukung. Fabric menghasilkan token sesuai dengan audiens yang dikonfigurasi untuk cloud saat ini, dan mengirimkannya ke visual.
Visual kemudian dapat menggunakan token untuk mengautentikasi terhadap audiens masing-masing, mewakili layanan backend-nya:

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

Dalam file pbiviz.json, atur versi API ke 5.9.1 atau yang lebih tinggi:

AcquireAADTokenService yang baru diekspos berisi dua metode:

  • acquireAADToken: Mengembalikan payload token autentikasi jenis AcquireAADTokenResult untuk visual atau null jika tidak dapat diambil.

     /**
 * 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: Mengembalikan salah satu status hak istimewa berikut yang terkait dengan memperoleh token.

    • Diizinkan: Hak istimewa diizinkan di lingkungan saat ini.
    • NotDeclared: Deklarasi hak istimewa hilang di bagian kemampuan visual.
    • NotSupported: Hak istimewa tidak didukung di lingkungan saat ini.
    • DisabledByAdmin: Administrator Fabric menolak penggunaan hak istimewa.

Contoh kode berikut menunjukkan cara memperoleh token ID Microsoft Entra menggunakan API:

    // 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

Pertimbangan dan batasan

Akuisisi token diblokir jika salah satu kondisi berikut berlaku:

  • Sakelar penyewa dimatikan.

  • Pengguna tidak masuk (di Desktop).

  • ISV tidak melakukan pra-otorisasi aplikasi Power BI.

  • Format parameter hak istimewa AADAuthentication tidak valid.

  • Visual tidak disetujui secara publik atau bukan visual debug.

  • Layanan backend visual, yang dikonfigurasi sebagai audiens oleh visual, tidak memiliki persetujuan yang sesuai untuk Graph API di penyewa konsumen menggunakan visual. Untuk informasi selengkapnya tentang persetujuan, lihat persetujuan administrator penyewa.

Konten terkait

Penyiapan aplikasi ID Microsoft Entra