API d’authentification

L’API d’authentification permet aux visuels d’obtenir des jetons d’accès Microsoft Entra ID (anciennement Azure AD) pour les utilisateurs connectés, ce qui facilite l’authentification unique.

Les administrateurs Power BI peuvent activer ou désactiver l’API via un commutateur global. Le paramètre par défaut bloque (désactive) l’API.

L’API s’applique uniquement aux visuels AppSource et non aux visuels privés. Les visuels sous développement peuvent être testés en mode débogage avant leur publication.

Environnements pris en charge

Les environnements suivants sont pris en charge :

  • Le Web
  • Bureau
  • RS Desktop
  • Mobile

Environnements non pris en charge

Les environnements suivants ne sont pas encore pris en charge :

  • RS Service
  • Analytique incorporée
  • Teams

Comment utiliser l’API d’authentification

Dans le fichier capabilities.json, ajoutez le privilège AADAuthentication avec l’URI de l’application enregistrée dans Microsoft Entra ID pour chaque cloud pris en charge. Fabric génère un jeton en fonction de l’audience configurée pour le cloud actuel et le remet au visuel.
Le visuel peut ensuite utiliser le jeton pour s’authentifier auprès de l’audience respective, représentant son service principal :

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

Dans le fichier pbiviz.json , définissez la version de l’API sur 5.9.1 ou une version ultérieure :

AcquireAADTokenService nouvellement exposé contient deux méthodes :

  • acquireAADToken : retourne un jeton d’authentification de type AcquireAADTokenResult pour le visuel ou null s’il ne peut pas être récupéré.

     /**
 * 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 : retourne l’un des états de privilège suivants associés à l’acquisition du jeton.

    • Autorisé : le privilège est autorisé dans l’environnement actuel.
    • Non déclaré : la déclaration de privilège est manquante dans la section fonctionnalités visuelles.
    • NotSupported : le privilège n’est pas pris en charge dans l’environnement actuel.
    • DisabledByAdmin : l’administrateur Fabric a interdit l’utilisation des privilèges.

L’exemple de code suivant montre comment acquérir un jeton d’ID Microsoft Entra à l’aide de 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

Considérations et limitations

L’acquisition de jetons est bloquée si l’une des conditions suivantes s’applique :

  • Le commutateur de locataire est désactivé.

  • L’utilisateur n’est pas connecté (dans Desktop).

  • L’éditeur de logiciels indépendants n’a pas préauthorisé l’application Power BI.

  • Le format du paramètre de privilège AADAuthentication n’est pas valide.

  • Le visuel n’est pas approuvé publiquement ou n’est pas un visuel de débogage.

  • Le service de backend du visuel, configuré comme audience par le visuel, ne dispose pas des autorisations nécessaires pour l’API Graph dans le locataire consommateur utilisant le visuel. Pour plus d’informations sur le consentement, consultez le consentement de l’administrateur client.

Contenu connexe

Configuration de l’application Microsoft Entra ID

  • Last updated on