İngilizce dilinde oku

Aracılığıyla paylaş

Kimlik Doğrulama API'si

  • Makale

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:

  • Web
  • Masaüstü
  • RS Masaüstü
  • Mobil

Desteklenmeyen ortamlar

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

  • RS Hizmeti
  • Eklenmiş analiz
  • Teams

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. Doku, geçerli bulut için yapılandırılan hedef kitleye göre bir belirteç oluşturur ve bunu görsele sunar.
Görsel daha sonra belirteci kullanarak arka uç hizmetini temsil ederek ilgili hedef kitlede kimlik doğrulaması yapabilir:

JSON 
"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 kimlik doğrulama belirteci yükü AcquireAADTokenResult veya getirilemiyorsa null döndürür.

    TypeScript 
     /**
 * 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.
    • DisabledBy Yönetici: Doku yöneticisi ayrıcalık kullanımını reddetti.

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

TypeScript 
    // 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 edilecekler ve sınırlamalar

Aşağıdaki koşullardan herhangi biri geçerliyse belirteç alımı 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