Edit

Authentication API

  • Article

The Authentication API enables visuals to obtain Microsoft Entra ID (formerly known as Azure AD) access tokens for signed-in users, facilitating single sign-on authentication.

Power BI administrators can enable or disable the API through a global switch. The default setting blocks (disables) the API.

The API is applicable only for AppSource visuals, and not for private visuals. Visuals that are under development can be tested in debug mode before they're published.

Supported environments

The following environments are supported:

  • Web
  • Desktop
  • RS Desktop
  • Mobile

Unsupported environments

The following environments aren't yet supported:

  • Sovereign clouds
  • RS Service
  • Embedded analytics
  • Teams

How to use the Authentication API

In the capabilities.json file, add the "AADAuthentication" privilege with your Microsoft Entra ID registered application URI. Fabric will generate a token with this audience, and deliver it to the visual.
The visual can then utilize the token to authenticate against the audience https://contoso.com, representing its backend service:

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

In the pbiviz.json file, set the API version to 5.9.0 or higher:

The newly exposed AcquireAADTokenService contains two methods:

  • acquireAADToken: Returns an authentication token payload of type AcquireAADTokenResult for the visual or null if it can't be fetched.

    /**
* 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: Returns one of the following privilege statuses associated with acquiring the token.

    • Allowed: The privilege is allowed in the current environment.
    • NotDeclared: The privilege declaration is missing in visual capabilities section.
    • NotSupported: The privilege isn't supported in the current environment.
    • DisabledByAdmin: The Fabric administrator denied privilege usage.

The following sample code demonstrates how to acquire a Microsoft Entra ID token using the 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

Considerations and limitations

Token acquisition is blocked if any of the following conditions apply:​

  • The tenant switch is turned off.

  • The user isn't signed in (in Desktop).

  • The ISV didn't preauthorize the Power BI application.

  • The format of the AADAuthentication privilege parameter is invalid.

  • The visual isn't publicly approved or isn't a debug visual.

  • The visual’s backend service, configured as the audience by the visual, doesn't have appropriate consents for the Graph API in the consumer tenant using the visual. For more about consents, see tenant administrator consent.

Related content

Microsoft Entra ID application setup