Delen via

Verificatie-API

  • Artikel

Met de verificatie-API kunnen visuals toegangstokens van Microsoft Entra ID (voorheen Bekend als Azure AD) verkrijgen voor aangemelde gebruikers, waardoor verificatie met eenmalige aanmelding wordt vergemakkelijkt.

Power BI-beheerders kunnen de API in- of uitschakelen via een globale switch. De STANDAARDinstelling blokkeert (schakelt) de API uit.

De API is alleen van toepassing voor AppSource-visuals en niet voor privévisuals. Visuals die in ontwikkeling zijn, kunnen worden getest in de foutopsporingsmodus voordat ze worden gepubliceerd.

Ondersteunde omgevingen

De volgende omgevingen worden ondersteund:

  • Web
  • Desktop
  • RS Desktop
  • Mobiel

Niet-ondersteunde omgevingen

De volgende omgevingen worden nog niet ondersteund:

  • RS-service
  • Ingesloten analyses
  • Teams

De verificatie-API gebruiken

Voeg in het capabilities.json-bestand de bevoegdheid AADAuthentication toe met een geregistreerde Microsoft Entra ID-toepassings-URI voor elke ondersteunde cloud. Fabric genereert een token op basis van de doelgroep die is geconfigureerd voor de huidige cloud en levert het aan de visual.
De visual kan vervolgens het token gebruiken om te verifiëren bij de respectieve doelgroep, die de back-endservice vertegenwoordigt:

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

Stel in het bestand pbiviz.json de API-versie in op 5.9.1 of hoger:

De nieuw weergegeven AcquireAADTokenService bevat twee methoden:

  • acquireAADToken: retourneert een nettolading van het verificatietoken van het type AcquireAADTokenResult voor de visual of null als deze niet kan worden opgehaald.

     /**
 * 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: retourneert een van de volgende bevoegdhedenstatussen die zijn gekoppeld aan het verkrijgen van het token.

    • Toegestaan: De bevoegdheid is toegestaan in de huidige omgeving.
    • NotDeclared: De bevoegdheidsdeclaratie ontbreekt in de sectie visuele mogelijkheden.
    • NotSupported: de bevoegdheid wordt niet ondersteund in de huidige omgeving.
    • DisabledBy Beheer: De Fabric-beheerder heeft het gebruik van bevoegdheden geweigerd.

De volgende voorbeeldcode laat zien hoe u een Microsoft Entra ID-token verkrijgt met behulp van de 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

Overwegingen en beperkingen

Het verkrijgen van tokens wordt geblokkeerd als een van de volgende voorwaarden van toepassing is:

  • De tenantswitch is uitgeschakeld.

  • De gebruiker is niet aangemeld (in Desktop).

  • De ISV heeft de Power BI-toepassing niet vooraf geverifieerd.

  • De indeling van de parameter AADAuthentication-bevoegdheden is ongeldig.

  • De visual is niet openbaar goedgekeurd of is geen foutopsporingsvisual.

  • De back-endservice van de visual, die is geconfigureerd als de doelgroep door de visual, heeft geen juiste toestemming voor de Graph API in de tenant voor consumenten met behulp van de visual. Zie toestemming van de tenantbeheerder voor meer informatie over toestemming.

Gerelateerde inhoud

Microsoft Entra ID-toepassing instellen