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 suivre 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 étendues ajoutées pour les API de plan de contrôle doivent préauthoriser 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 une étendue pour l’API du plan de contrôle pour que le flux fonctionne.
Les étendues ajoutées pour les API de plan de données doivent préauthoriser Microsoft Power BI avec l’ID d’application
871c010f-5e61-4fb1-83ac-98610a7e9110. Ils sont inclus dans le jeton retourné par l’API JavaScriptacquireAccessToken.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 d’étendues pour chaque API exposée par le back-end de charge de travail et vérifier que le jeton reçu inclut ces étendues lorsque ces API sont appelées à partir du client. Par exemple:
- La charge de travail expose deux API au client,
ReadDataetWriteData. - La charge de travail expose deux étendues de plan de données,
data.readetdata.write. - Dans l’API
ReadData, la charge de traitement valide que l’étenduedata.readest incluse dans le jeton avant de poursuivre le processus. La même chose s’applique àWriteData.
- La charge de travail expose deux API au client,
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 toutes les étendues dont votre charge de travail a besoin pour échanger un jeton. Une étendue obligatoire à ajouter est Fabric.Extend sous le service Power BI. Les demandes adressées à Fabric peuvent échouer sans cette étendue.
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 comment le serveur frontal de charge de travail doit utiliser le de l’API JavaScript
É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’accueil 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 l’API JavaScript acquireAccessToken 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/workspacesCré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.Allouhttps://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All - Pour créer un entrepôt :
https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.Allouhttps://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 étendues mentionnées précédemment doivent être configurées 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 :
L'interface de charge de travail demande un jeton à l'aide de l'API JavaScript.
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.
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.Allpar exemple).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 ).
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 l’API JavaScript
acquireAccessTokenet fournitadditionalScopesToConsent: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 invite 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) :
L'interface utilisateur de la gestion des tâches appelle l'API JavaScript 'Créer un Élément'.
Le back-end de charge de travail reçoit un appel de Fabric et extrait le jeton délégué et le valide.
La charge de travail tente d’échanger le jeton pour
https://storage.azure.com/user_impersonationmais échoue, car l’administrateur client de l’authentification multifacteur configurée par l’utilisateur nécessaire pour accéder au stockage Azure (voir codes d’erreur AADSTS).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.
Le frontend de la charge de travail appelle l'API JavaScript
acquireAccessTokenet fournit des demandes en tant queclaimsForConditionalAccessPolicy, oùclaimsfait 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.