Jaa

Todentamisen ohjelmointirajapinta

Authentication API mahdollistaa visuaaleille Microsoft Entra ID:n (entinen Azure AD) käyttötunnuksia kirjautuneille käyttäjille, mikä helpottaa kertakirjautumisen tunnistautumista.

Power BI:n ylläpitäjät voivat ottaa API:n käyttöön tai poistaa käytöstä globaalin kytkimen kautta. Oletusasetukset estävät (poistavat käytöstä) API:n.

API koskee vain AppSource-visuaaleja, ei yksityisiä visuaaleja. Kehitteillä olevia visuaaleja voidaan testata debug-tilassa ennen julkaisua.

Tuetut ympäristöt

Seuraavat ympäristöt ovat tuettuja:

  • verkko
  • Työpöytä
  • RS Desktop
  • Mobile

Tuettomat ympäristöt

Seuraavat ympäristöt eivät ole vielä tuettuja:

  • RS-palvelu
  • Upotettu analytiikka
  • Teams

Kuinka käyttää Authentication API:ta

Lisääcapabilities.json-tiedostoon "AADAuthentication" -oikeus Microsoft Entra ID -rekisteröidyn sovelluksen URI:n kanssa jokaiselle tuetulle pilvelle. Fabric generoi tokenin nykyisen pilven yleisön mukaan ja toimittaa sen visuaalille.
Visuaalinen käyttäjä voi sitten käyttää tokenia tunnistautuakseen kyseistä yleisöä vastaan, edustaen sen taustapalvelua:

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

pbiviz.json-tiedostossa aseta API-versioksi 5.9.1 tai uudempi:

Uusi AcquireAADTokenService sisältää kaksi menetelmää:

  • acquireAADToken: Palauttaa autentikointitokenin hyötykuorman AcquireAADTokenResult visuaaliselle tai nullille, jos sitä ei voi hakea.

     /**
 * 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: Palauttaa yhden seuraavista tokenin hankintaan liittyvistä etuoikeusstatuksista.

    • Sallittu: Etuoikeus on sallittu nykyisessä ympäristössä.
    • NotDeclared: Etuoikeusilmoitus puuttuu visuaalisten kykyjen osiosta.
    • NotSupported: Etuoikeutta ei tueta nykyisessä ympäristössä.
    • DisabledByAdmin: Fabric-ylläpitäjä eväsi oikeuksien käytön.

Seuraava esimerkkikoodi osoittaa, miten Microsoft Entra ID -tunniste saadaan API:n avulla:

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

Huomioitavat asiat ja rajoitukset

Tokenien hankinta estetään, jos jokin seuraavista ehdoista on voimassa:

  • Vuokralaisen kytkin on pois päältä.

  • Käyttäjä ei ole kirjautuneena sisään (työpöydällä).

  • ISV ei ollut ennakkovaltuuttanut Power BI -sovellusta.

  • AADAuthentication -etuoikeusparametrin muoto on virheellinen.

  • Visuaalinen näyttö ei ole julkisesti hyväksytty eikä se ole virheenkorjausvisuaali.

  • Visualin taustapalvelu, jonka visuaali määrittelee yleisöksi, ei saa asianmukaisia suostumuksia Graph-API:lle kuluttajavuokralaisessa visuaalin avulla. Lisätietoja suostumuksesta löytyy vuokralaisen ylläpitäjän suostumuksesta.

Liittyvä sisältö

Microsoft Entra ID application setup

  • Last updated on