Udostępnij za pośrednictwem

Interfejs API uwierzytelniania

  • Artykuł

Interfejs API uwierzytelniania umożliwia wizualizacjom uzyskiwanie tokenów dostępu microsoft Entra ID (wcześniej znanych jako Azure AD) dla zalogowanych użytkowników, co ułatwia uwierzytelnianie przy użyciu logowania jednokrotnego.

Administratorzy usługi Power BI mogą włączać lub wyłączać interfejs API za pośrednictwem przełącznika globalnego. Domyślne ustawienia blokują (wyłącza) interfejs API.

Interfejs API ma zastosowanie tylko dla wizualizacji usługi AppSource, a nie w przypadku wizualizacji prywatnych. Wizualizacje, które są opracowywane, mogą być testowane w trybie debugowania przed ich opublikowaniem.

Obsługiwane środowiska

Obsługiwane są następujące środowiska:

  • Internet
  • Klasyczna
  • RS Desktop
  • Aplikacje mobilne

Nieobsługiwane środowiska

Następujące środowiska nie są jeszcze obsługiwane:

  • Usługa RS
  • Osadzona analiza
  • Teams

Jak używać interfejsu API uwierzytelniania

W pliku capabilities.json dodaj uprawnienie "AADAuthentication" z identyfikatorem URI zarejestrowanej aplikacji firmy Microsoft dla każdej obsługiwanej chmury. Sieć szkieletowa generuje token zgodnie z odbiorcami skonfigurowanymi dla bieżącej chmury i dostarcza go do wizualizacji.
Wizualizacja może następnie używać tokenu do uwierzytelniania względem odpowiednich odbiorców reprezentujących usługę zaplecza:

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

W pliku pbiviz.json ustaw wersję interfejsu API na 5.9.1 lub nowszą:

Nowo uwidoczniona usługa AcquireAADTokenService zawiera dwie metody:

  • acquireAADToken: zwraca ładunek tokenu uwierzytelniania typu AcquireAADTokenResult dla wizualizacji lub wartości null, jeśli nie można go pobrać.

     /**
 * 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: zwraca jeden z następujących stanów uprawnień skojarzonych z uzyskaniem tokenu.

    • Dozwolone: uprawnienie jest dozwolone w bieżącym środowisku.
    • NotDeclared: brak deklaracji uprawnień w sekcji możliwości wizualizacji.
    • Nieobsługiwane: uprawnienie nie jest obsługiwane w bieżącym środowisku.
    • DisabledBy Administracja: Administrator sieci szkieletowej odmówił użycia uprawnień.

Poniższy przykładowy kod pokazuje, jak uzyskać token identyfikatora entra firmy Microsoft przy użyciu interfejsu 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

Rozważania i ograniczenia

Uzyskiwanie tokenu jest blokowane, jeśli obowiązują jakiekolwiek z następujących warunków:

  • Przełącznik dzierżawy jest wyłączony.

  • Użytkownik nie jest zalogowany (w programie Desktop).

  • Niezależnego dostawcy oprogramowania nie wstępnie uwierzytelniało aplikacji usługi Power BI.

  • Format parametru uprawnień AADAuthentication jest nieprawidłowy.

  • Wizualizacja nie jest publicznie zatwierdzona lub nie jest wizualizacją debugowania.

  • Usługa zaplecza wizualizacji skonfigurowana jako odbiorcy w wizualizacji nie ma odpowiednich zgody dla interfejsu API programu Graph w dzierżawie odbiorcy przy użyciu wizualizacji. Aby uzyskać więcej informacji na temat zgody, zobacz Zgoda administratora dzierżawy.

Powiązana zawartość

Konfiguracja aplikacji Microsoft Entra ID