Kimlik Doğrulama API'si

Kimlik Doğrulama API'si, görsellerin oturum açmış kullanıcılar için Microsoft Entra Id (eski adıyla Azure AD) erişim belirteçleri edinerek çoklu oturum açma kimlik doğrulamasını kolaylaştırmalarına olanak tanır.

Power BI yöneticileri genel anahtar aracılığıyla API'yi etkinleştirebilir veya devre dışı bırakabilir. Varsayılan ayar API'yi engeller (devre dışı bırakır).

API yalnızca AppSource görselleri için geçerlidir, özel görseller için geçerli değildir. Geliştirme aşamasında olan görseller yayımlanmadan önce hata ayıklama modunda test edilebilir.

Desteklenen ortamlar

Aşağıdaki ortamlar desteklenir:

  • İnternet
  • Desktop
  • RS Masaüstü
  • Cep telefonu

Desteklenmeyen ortamlar

Aşağıdaki ortamlar henüz desteklenmiyor:

  • RS Hizmeti
  • Tümleşik analiz
  • Takımlar

Kimlik Doğrulama API'sini kullanma

capabilities.json dosyasında, desteklenen her bulut için Microsoft Entra ID kayıtlı uygulama URI'si ile "AADAuthentication" ayrıcalığını ekleyin. Fabric, mevcut bulut için yapılandırılan hedef kitlenin gereksinimlerine göre bir belirteç oluşturur ve bunu bileşene teslim eder.
Görsel daha sonra belirteci kullanarak arka uç hizmetini temsil ederek ilgili hedef kitlede kimlik doğrulaması yapabilir:

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

pbiviz.json dosyasında API sürümünü 5.9.1 veya üzeri olarak ayarlayın:

Yeni kullanıma sunulan AcquireAADTokenService iki yöntem içerir:

  • acquireAADToken: Görsel için AcquireAADTokenResult türünde kimlik doğrulama belirteci yükü ya da getirilemiyorsa null geri döndürür.

     /**
 * 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: Belirteci almayla ilişkili aşağıdaki ayrıcalık durumlarından birini döndürür.

    • İzin verildi: Geçerli ortamda ayrıcalıklara izin verilir.
    • NotDeclared: Görsel yetenekler bölümünde ayrıcalık bildirimi eksik.
    • NotSupported: Ayrıcalık geçerli ortamda desteklenmiyor.
    • DisabledByAdmin: Kumaş yöneticisi ayrıcalık kullanımını engelledi.

Aşağıdaki örnek kod, API'yi kullanarak bir Microsoft Entra ID belirtecinin nasıl alınduğunu gösterir:

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

Dikkat edilmesi gerekenler ve sınırlamalar

Aşağıdaki koşullardan herhangi biri geçerliyse jeton edinimi engellenir.

  • Kiracı anahtarı kapalı.

  • Kullanıcı oturum açmamış (Masaüstünde).

  • ISV, Power BI uygulamasının ön yetkilendirmesini yapmadı.

  • AADAuthentication privilege parametresinin biçimi geçersiz.

  • Görsel genel olarak onaylanmamış veya bir hata ayıklama görseli değildir.

  • Görsel tarafından hedef kitle olarak yapılandırılan görselin arka uç hizmeti, görseli kullanan tüketici kiracısında Graph API'sine uygun onaylara sahip değildir. Onay hakkında daha fazla bilgi için bkz. kiracı yöneticisi onayı.

İlgili içerik

Microsoft Entra Id uygulama kurulumu

  • Last updated on