Compartir a través de

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:

  • 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 para cada nube compatible. Fabric genera un token según la audiencia configurada para la nube actual y la entrega al objeto visual.
A continuación, el objeto visual puede usar el token para autenticarse en la respectiva audiencia, 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 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 del tipo AcquireAADTokenResult para el objeto visual o null si no se puede capturar.

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

    • 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 el consentimiento, consulte Consentimiento del administrador de inquilinos.

Contenido relacionado

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