API de autenticación

La API de autenticación permite a las visualizaciones obtener tokens de acceso de Microsoft Entra ID (anteriormente conocidos como Azure AD) para los usuarios autenticados, lo que facilita la autenticación de inicio de sesión único.

Los administradores de Power BI pueden habilitar o deshabilitar la API a través de un conmutador global. La configuración predeterminada bloquea (deshabilita) la API.

La API solo es aplicable a los objetos visuales de AppSource y no a los objetos visuales privados. Los elementos visuales que están en desarrollo pueden probarse en modo de depuración antes de publicarse.

Entornos soportados

Se admiten los siguientes entornos:

• Web
• Escritorio
• Escritorio de RS
• Móvil

Entornos no compatibles

Todavía no se admiten los siguientes entornos:

• Servicio RS
• Analítica integrada
• Equipos

Uso de la API de autenticación

En el archivo capabilities.json , agregue el privilegio "AADAuthentication" con un URI de aplicación registrado de Microsoft Entra ID para cada nube compatible. Fabric genera un token según la audiencia configurada para la nube actual y lo entrega al elemento visual.
A continuación, el objeto visual puede usar el token para autenticarse frente a la audiencia respectiva, que representa su servicio backend.

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

En el archivo pbiviz.json , establezca la versión de la API en 5.9.1 o posterior:

El objeto AcquireAADTokenService recién expuesto contiene dos métodos:

• acquireAADToken: devuelve una carga de token de autenticación de tipo AcquireAADTokenResult para la visualización o null si no se puede coger.

   /**
   * 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: devuelve uno de los siguientes estados de privilegios asociados a la adquisición del token.

  • Permitido: el privilegio se permite en el entorno actual.
  • NotDeclared: falta la declaración de privilegios en la sección funcionalidades visuales.
  • NotSupported: El privilegio no es compatible con el entorno actual.
  • DisabledByAdmin: el administrador de Fabric denegó el uso de privilegios.

En el código de ejemplo siguiente se muestra cómo adquirir un token de id. de Microsoft Entra mediante la 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 

Consideraciones y limitaciones

La adquisición de tokens se bloquea si se aplica alguna de las condiciones siguientes:

• El interruptor de inquilino está apagado.

• El usuario no ha iniciado sesión (en Escritorio).

• El ISV no ha autenticado previamente la aplicación de Power BI.

• El formato del parámetro de privilegio AADAuthentication no es válido.

• El objeto visual no está aprobado públicamente o no es un objeto visual de depuración.

• El servicio back-end del objeto visual, configurado como público por el objeto visual, no tiene los consentimientos adecuados para Graph API en el inquilino del consumidor mediante el objeto visual. Para más información sobre el consentimiento, consulte Consentimiento del administrador de inquilinos.

Contenido relacionado

Configuración de la aplicación Microsoft Entra ID