Condividi tramite

API di autenticazione

L'API di autenticazione consente agli oggetti visivi di ottenere i token di accesso di Microsoft Entra ID (in precedenza noti come Azure AD) per gli utenti connessi, semplificando l'autenticazione Single Sign-On.

Gli amministratori di Power BI possono abilitare o disabilitare l'API tramite un commutatore globale. L'impostazione predefinita blocca (disabilita) l'API.

L'API è applicabile solo per gli oggetti visivi di AppSource e non per gli oggetti visivi privati. Gli oggetti visivi in fase di sviluppo possono essere testati in modalità di debug prima della pubblicazione.

Ambienti supportati

Sono supportati i seguenti ambienti:

  • Web
  • Desktop
  • RS Desktop
  • Dispositivi mobili

Ambienti non supportati

Gli ambienti seguenti non sono ancora supportati:

  • Servizio RS
  • Analisi incorporata
  • Teams

Come usare l'API di autenticazione

Nel file capabilities.json, aggiungere il privilegio "AADAuthentication" con un URI di un'applicazione registrata tramite ID Entra Microsoft per ogni cloud supportato. Fabric genera un token in base al gruppo di destinatari configurato per il cloud corrente e lo distribuisce all'oggetto visivo.
L'oggetto visivo può quindi usare il token per autenticarsi con il rispettivo pubblico di destinazione, rappresentando il suo servizio back-end.

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

Nel file pbiviz.json impostare la versione dell'API su 5.9.1 o versione successiva:

AcquireAADTokenService appena esposto contiene due metodi:

  • acquireAADToken: restituisce un token di autenticazione con payload di tipo AcquireAADTokenResult per l'oggetto visivo o null se non può essere recuperato.

     /**
 * 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: restituisce uno degli stati dei privilegi seguenti associati all'acquisizione del token.

    • Consentito: il privilegio è consentito nell'ambiente corrente.
    • NotDeclared: la dichiarazione dei privilegi non è presente nella sezione funzionalità visive.
    • NotSupported: il privilegio non è supportato nell'ambiente corrente.
    • DisabledByAdmin: l'amministratore dell'infrastruttura ha negato l'utilizzo dei privilegi.

Il codice di esempio seguente illustra come acquisire un token ID Microsoft Entra usando l'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

Considerazioni e limitazioni

L'acquisizione del token viene bloccata se si applica una delle condizioni seguenti:

  • L'interruttore del tenant è disattivato.

  • L'utente non ha eseguito l'accesso (sul Desktop).

  • L'ISV non ha preautenticato l'applicazione Power BI.

  • Il formato del parametro del privilegio AADAuthentication non è valido.

  • L'oggetto visivo non è approvato pubblicamente o non è un oggetto visivo di debug.

  • Il servizio back-end del componente visivo, configurato come pubblico dal componente visivo, non dispone del consenso appropriato per l'API Graph nel tenant consumer che utilizza il componente visivo. Per ulteriori informazioni sul consenso, consulta consenso dell'amministratore del tenant.

Contenuti correlati

Configurazione dell'applicazione Microsoft Entra ID

  • Last updated on