API de Autenticación

  • Artículo

La API de autenticación permite a los objetos visuales obtener tokens de acceso de Microsoft Entra ID (anteriormente conocido como Azure AD) para los usuarios que han iniciado sesión, lo que facilita la autenticación de inicio de sesión único.

Los administradores de Power BI pueden habilitar o deshabilitar la API mediante un modificador 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 objetos visuales que están en desarrollo se pueden probar en modo de depuración antes de que se publiquen.

Entornos admitidos

Se admiten los siguientes entornos:

  • Web
  • Escritorio
  • Escritorio RS
  • Dispositivo móvil

Entornos no admitidos

Todavía no se admiten los siguientes entornos:

  • Nubes soberanas
  • Servicio RS
  • Análisis insertados
  • Teams

Uso de la API de autenticación

En el archivo capabilities.json, agregue el privilegio "AADAuthentication" con el identificador URI de la aplicación registrada de Microsoft Entra ID. Fabric generará un token con esta audiencia y lo entregará al objeto visual.
A continuación, el objeto visual puede usar el token para autenticarse en la audiencia https://contoso.com, que representa su servicio back-end:

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

En el archivo pbiviz.json, establezca la versión de API en 5.9.0 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 el objeto visual o null si no se puede capturar.

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

  • acquireAADTokenstatus: devuelve uno de los siguientes estados de privilegios asociados a la adquisición del token.

    • Allowed: el privilegio se permite en el entorno actual.
    • NotDeclared: falta la declaración de privilegios en la sección de funcionalidades del objeto visual.
    • NotSupported: el privilegio no se admite en 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 Microsoft Entra ID 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 modificador de inquilino está desactivado.

  • El usuario no ha iniciado sesión (en el 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 audiencia por el objeto visual, no tiene los consentimientos adecuados para Graph API en el inquilino del consumidor con el objeto visual. Para obtener más información sobre los consentimientos, consulte Consentimiento de administrador de inquilinos.

Contenido relacionado

Configuración de la aplicación de Microsoft Entra ID