Vue d’ensemble des instructions d’authentification de charge de travail dans Microsoft Fabric

Cet article fournit des instructions sur l’utilisation de l’authentification lorsque vous créez des charges de travail Microsoft Fabric. Il inclut des informations sur l’utilisation des jetons et des consentements.

Avant de commencer, assurez-vous que vous connaissez les concepts de Vue d’ensemble de l’authentification et Configuration de l’authentification.

API de plan de données et de plan de contrôle

• Les APIs du plan de données sont des APIs exposées par le serveur principal de charge de travail. Le serveur frontal de charge de travail peut les appeler directement. Pour les API de plan de données, le back-end de charge de travail peut décider des API à exposer.

• Les API du plan de contrôle sont des interfaces qui transitent par Fabric. Le processus commence par le front-end de charge de travail appelant une API JavaScript et se termine par Fabric appelant le back-end de charge de travail. Par exemple, une telle API est Créer un élément.

  Pour les API de plan de contrôle, la charge de travail doit respecter les contrats définis dans le back-end de charge de travail et implémenter ces API.

Exposer un onglet API sur l'application de la charge de travail dans Microsoft Entra Identité

Sous l’onglet Exposer une API, vous devez ajouter les étendues pour les API du plan de contrôle et les API du plan de données.

• Les périmètres ajoutés pour les API de plan de contrôle doivent autoriser préalablement l’application Fabric Client for Workloads avec l’ID d’application d2450708-699c-41e3-8077-b0c8341509aa. Ces étendues sont incluses dans le jeton que le backend de la charge de travail reçoit lorsque Fabric l’appelle.

  Vous devez ajouter au moins un périmètre pour l’API du plan de contrôle pour que le flux fonctionne.

• Les périmètres ajoutés pour les API de plan de données doivent autoriser préalablement Microsoft Power BI avec l’ID d’application 871c010f-5e61-4fb1-83ac-98610a7e9110. Ils sont inclus dans le jeton retourné par acquireAccessTokenl’API JavaScript.

  Pour les API de plan de données, vous pouvez utiliser cet onglet pour gérer les autorisations granulaires pour chaque API exposée par votre charge de travail. Dans l’idéal, vous devez ajouter un ensemble de périmètres pour chaque API exposée par le back-end de charge de travail et vérifier que le jeton reçu inclut ces périmètres lorsque ces API sont appelées à partir du client. Exemple :

  • La charge de travail expose deux API au client, ReadData et WriteData.
  • La charge de travail expose deux étendues de plan de données, data.read et data.write.
  • Dans l’API ReadData, la charge de traitement valide que l’étendue data.read est incluse dans le jeton avant de poursuivre le processus. Il en va de même pour les WriteData.

Onglet Autorisations d’API sur l’application de la charge de travail dans l’ID Microsoft Entra

Sous l’onglet Autorisations d’API, vous devez ajouter tous les périmètres dont votre charge de travail a besoin pour échanger un jeton. Un périmètre obligatoire à ajouter est Fabric.Extend sous le service Power BI. Les demandes adressées à Fabric peuvent échouer sans ce périmètre.

Utiliser des jetons et des consentements

Lorsque vous travaillez avec des API de plan de données, le frontend de la charge de travail doit acquérir un jeton pour les appels au backend de la charge de travail.

Les sections suivantes décrivent la manière dont la charge de travail devrait utiliser l’API JavaScript et les flux OBO (on-behalf-of) afin d’acquérir des jetons pour la charge de travail et les services externes, et pour travailler avec des consentements.

Étape 1 : Acquérir un jeton

La charge de travail commence par demander un jeton à l’aide de l’API JavaScript sans fournir de paramètres. Cet appel peut entraîner deux scénarios :

• L’utilisateur voit une fenêtre de consentement de toutes les dépendances statiques (ce qui est configuré sous l’onglet Autorisations d’API) configurées par la charge de travail. Ce scénario se produit si l’utilisateur ne fait pas partie du locataire d’origine de l’application et que l’utilisateur n’a pas accordé son consentement à Microsoft Graph pour cette application avant.

• L’utilisateur ne voit pas de fenêtre de consentement. Ce scénario se produit si l'utilisateur a déjà donné son consentement au moins une fois à Microsoft Graph pour cette application, ou si l'utilisateur fait partie du locataire de l'application.

Dans les deux scénarios, la charge de travail ne doit pas s’occuper si l’utilisateur a donné son consentement complet pour toutes les dépendances (et ne peut pas savoir à ce stade). Le jeton reçu a l’audience du back-end de charge de travail et peut être utilisé pour appeler directement le serveur principal de charge de travail à partir du serveur frontal de charge de travail.

Étape 2 : Essayer d’accéder aux services externes

La charge de travail peut avoir besoin d’accéder aux services qui nécessitent une authentification. Pour cet accès, il doit effectuer le flux OBO, où il échange le jeton reçu de son client ou de Fabric vers un autre service. L’échange de jetons peut échouer en raison d’un manque de consentement ou d’une stratégie d’accès conditionnel Microsoft Entra configurée sur la ressource pour laquelle la charge de travail tente d’échanger le jeton.

Pour résoudre ce problème, il incombe à la charge de travail de propager l’erreur au client lors de l’utilisation d’appels directs entre le front-end et le back-end. Il est également de la responsabilité de la charge de travail de propager l'erreur au client lors de l'utilisation des appels provenant de Fabric, en suivant la propagation de l'erreur décrite dans la section Communication de charge de travail.

Une fois que la charge de travail a propagé l’erreur, elle peut appeler acquireAccessToken l’API JavaScript pour résoudre le problème de stratégie de consentement ou d’accès conditionnel et réessayer l’opération.

Pour comprendre les défaillances des API du plan de contrôle de données, consultez Gestion de l'authentification multifacteur, de l'accès conditionnel ainsi que du consentement incrémentiel. Pour connaître les échecs d’API du plan de contrôle, consultez communication de charge de travail .

Exemples de scénarios

Examinons une charge de travail qui doit accéder à trois API Fabric :

• Répertorier les espaces de travail : GET https://api.fabric.microsoft.com/v1/workspaces

• Créer un entrepôt : POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Écrire dans un fichier lakehouse : PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Pour pouvoir utiliser ces API, le back-end de charge de travail doit échanger des jetons pour les étendues suivantes :

• Pour répertorier les espaces de travail : https://analysis.windows.net/powerbi/api/Workspace.Read.All ou https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Pour créer un entrepôt : https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All ou https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Pour écrire dans un fichier lakehouse : https://storage.azure.com/user_impersonation

Remarque

Vous trouverez les périmètres nécessaires pour chaque API Fabric dans cet article de référence.

Les périmètres mentionnés précédemment doivent être configurés sur l’application de charge de travail sous Autorisations d’API.

Examinons des exemples de scénarios que la charge de travail peut rencontrer.

Exemple 1

Supposons que le back-end de charge de travail dispose d’une API de plan de données qui obtient les espaces de travail de l’utilisateur et les retourne au client :

1. L'interface de charge de travail demande un jeton à l'aide de l'API JavaScript.

2. Le front-end de charge de travail appelle l’API back-end de charge de travail pour obtenir les espaces de travail de l’utilisateur et attacher le jeton dans la requête.

3. Le back-end de charge de travail valide le jeton et tente de l’échanger pour l’étendue requise (https://analysis.windows.net/powerbi/api/Workspace.Read.All par exemple).

4. La charge de travail ne parvient pas à échanger le jeton pour la ressource spécifiée, car l'utilisateur n'a pas consenti à ce que l'application accède à cette ressource (voir les codes d'erreur AADSTS ).

5. Le serveur principal de charge de travail propage l’erreur au serveur frontal de la charge de travail en spécifiant qu’il a besoin d’un consentement pour cette ressource. Le serveur frontal de charge de travail appelle acquireAccessTokenl’API JavaScript et fournit additionalScopesToConsent:

   workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

   Sinon, la charge de travail peut décider de demander le consentement pour toutes ses dépendances statiques configurées sur son application, de sorte qu’elle appelle l’API JavaScript et fournit promptFullConsent :

   workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Cet appel affiche une fenêtre de consentement, que l’utilisateur ait donné son consentement ou non à certaines des dépendances. Ensuite, le serveur frontal de la charge de travail peut réessayer l’opération.

Remarque

Si l’échange de jetons échoue toujours sur une erreur de consentement, cela signifie que l’utilisateur n’a pas accordé le consentement. La charge de travail doit gérer ces scénarios ; par exemple, informez l’utilisateur que cette API nécessite un consentement et ne fonctionnera pas sans elle.

Exemple 2

Supposons que le back-end de chargement de travail doit accéder à OneLake par l'API de création d'élément (appel de Fabric au chargement de travail) :

1. L'interface utilisateur de la gestion des tâches appelle l'API JavaScript 'Créer un Élément'.

2. Le back-end de charge de travail reçoit un appel de Fabric et extrait le jeton délégué et le valide.

3. La charge de travail tente d’échanger le jeton pour https://storage.azure.com/user_impersonation mais échoue, car l’administrateur du locataire de l’authentification multifacteurs configurée par l’utilisateur nécessaire pour accéder au stockage Azure (voir codes d’erreur AADSTS).

4. La charge de traitement propage l'erreur associée aux revendications retournées dans l'erreur de Microsoft Entra ID au client, en utilisant la propagation d'erreurs décrite dans communication de la charge de traitement.

5. Le frontend de la charge de travail appelle l'API JavaScript acquireAccessToken et fournit des demandes en tant que claimsForConditionalAccessPolicy, où claims fait référence aux demandes propagées à partir du backend de la charge de travail.

   workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

Après cela, la charge de travail peut réessayer l’opération.

Gérer les erreurs lors de la demande de consentements

Parfois, l’utilisateur ne peut pas accorder son consentement en raison de diverses erreurs. Après une demande de consentement, la réponse est retournée à l’URI de redirection. Dans notre exemple, ce code est responsable de la gestion de la réponse. (Vous pouvez le trouver dans le fichier index.ts.)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
} 

Le serveur frontal de la charge de travail peut extraire le code d’erreur de l’URL et le gérer en conséquence.

Remarque

Dans les deux scénarios (erreur et réussite), la charge de travail doit toujours fermer la fenêtre immédiatement, sans latence.