Επισκόπηση των οδηγιών ελέγχου ταυτότητας φόρτου εργασίας στο Microsoft Fabric
Αυτό το άρθρο παρέχει οδηγίες σχετικά με τον τρόπο εργασίας με τον έλεγχο ταυτότητας όταν δημιουργείτε φόρτους εργασίας Microsoft Fabric. Περιλαμβάνει πληροφορίες σχετικά με την εργασία με διακριτικά και συγκατάθεση.
Προτού ξεκινήσετε, βεβαιωθείτε ότι είστε εξοικειωμένοι με τις έννοιες στο Επισκόπηση ελέγχου ταυτότητας και στο ρύθμιση ελέγχου ταυτότητας.
API επιπέδου δεδομένων και επιπέδου ελέγχου
API επιπέδου δεδομένων είναι API που εκθέτει το παρασκήνιο φόρτου εργασίας. Το προσκήνιο φόρτου εργασίας μπορεί να τις καλέσει απευθείας. Για τα API επιπέδου δεδομένων, το παρασκήνιο φόρτου εργασίας μπορεί να αποφασίσει ποια API θα εκθέτει.
Έλεγχος API αεροπλάνου είναι API που περνούν από το Fabric. Η διαδικασία ξεκινά με τον φόρτο εργασίας να καλεί ένα JavaScript API και τελειώνει με κλήση του Fabric στο παρασκήνιο φόρτου εργασίας. Ένα παράδειγμα ενός τέτοιου API είναι η Δημιουργία στοιχείου.
Για τα API επιπέδου ελέγχου, ο φόρτος εργασίας πρέπει να ακολουθεί τις συμβάσεις που ορίζονται στο παρασκήνιο φόρτου εργασίας και να εφαρμόζει αυτά τα API.
Έκθεση μιας καρτέλας API στην εφαρμογή του φόρτου εργασίας στο αναγνωριστικό Microsoft Entra
Στην καρτέλα Έκθεση API, πρέπει να προσθέσετε εμβέλειες για API επιπέδου ελέγχου και εμβέλειες για API επιπέδου δεδομένων:
Οι εμβέλειες που προστίθενται για τα API επιπέδου ελέγχου θα πρέπει να εξουσιοδοτούν εκ των προτέρων την εφαρμογή Πρόγραμμα-πελάτης Fabric για φόρτους εργασίας με αναγνωριστικό εφαρμογής
d2450708-699c-41e3-8077-b0c8341509aa. Αυτές οι εμβέλειες περιλαμβάνονται στο διακριτικό που λαμβάνει το παρασκήνιο φόρτου εργασίας όταν το καλεί το Fabric.Για να λειτουργήσει η ροή, πρέπει να προσθέσετε τουλάχιστον μία εμβέλεια για το API επιπέδου ελέγχου.
Οι εμβέλειες που προστίθενται για API επιπέδου δεδομένων θα πρέπει να εξουσιοδοτούν εκ των προτέρων το Microsoft Power BI με αναγνωριστικό εφαρμογής
871c010f-5e61-4fb1-83ac-98610a7e9110. Περιλαμβάνονται στο διακριτικό που επιστρέφει τοacquireAccessTokenJavaScript API.Για API επιπέδου δεδομένων, μπορείτε να χρησιμοποιήσετε αυτήν την καρτέλα για να διαχειριστείτε λεπτομερή δικαιώματα για κάθε API που εκθέτει ο φόρτος εργασίας σας. Ιδανικά, θα πρέπει να προσθέσετε ένα σύνολο εμβέλειων για κάθε API που εκθέτει το παρασκήνιο φόρτου εργασίας και να επικυρώσετε ότι το διακριτικό που λάβατε περιλαμβάνει αυτές τις εμβέλειες όταν καλούνται αυτά τα API από το πρόγραμμα-πελάτη. Για παράδειγμα:
- Ο φόρτος εργασίας εκθέτει δύο API στον υπολογιστή-πελάτη, το
ReadDataκαι τοWriteData. - Ο φόρτος εργασίας εμφανίζει δύο εμβέλειες επιπέδου δεδομένων,
data.readκαιdata.write. - Στο
ReadDataAPI, ο φόρτος εργασίας επικυρώνει ότι η εμβέλειαdata.readπεριλαμβάνεται στο διακριτικό προτού συνεχίσει με τη ροή. Το ίδιο ισχύει και γιαWriteData.
- Ο φόρτος εργασίας εκθέτει δύο API στον υπολογιστή-πελάτη, το
Καρτέλα δικαιωμάτων API στην εφαρμογή του φόρτου εργασίας στο Αναγνωριστικό Microsoft Entra
Στην καρτέλα δικαιώματα API Fabric.Extend στην υπηρεσία Power BI. Οι αιτήσεις στο Fabric ενδέχεται να αποτύχουν χωρίς αυτή την εμβέλεια.
Εργασία με διακριτικά και συγκατάθεση
Όταν εργάζεστε με API επιπέδου δεδομένων, το προσκήνιο φόρτου εργασίας πρέπει να αποκτήσει ένα διακριτικό για κλήσεις στο παρασκήνιο φόρτου εργασίας.
Οι παρακάτω ενότητες περιγράφουν τον τρόπο με τον οποίο το προσκήνιο φόρτου εργασίας θα πρέπει να χρησιμοποιεί το API JavaScript και εκ μέρους (OBO) ροές για την απόκτηση διακριτικών για τον φόρτο εργασίας και εξωτερικές υπηρεσίες, καθώς και για την εργασία με συγκατάθεση.
Βήμα 1: Λήψη διακριτικού
Ο φόρτος εργασίας ξεκινά ζητώντας ένα διακριτικό χρησιμοποιώντας το JavaScript API χωρίς να παρέχονται παράμετροι. Αυτή η κλήση μπορεί να οδηγήσει σε δύο σενάρια:
Ο χρήστης βλέπει ένα παράθυρο συγκατάθεσης όλων των στατικών εξαρτήσεων (όσων έχουν ρυθμιστεί στην καρτέλα δικαιώματα A PI
) που έχει ρυθμιστεί από τον φόρτο εργασίας. Αυτό το σενάριο συμβαίνει εάν ο χρήστης δεν ανήκει στον κεντρικό μισθωτή της εφαρμογής και ο χρήστης δεν εκχωρήσει συγκατάθεση στο Microsoft Graph για αυτήν την εφαρμογή στο παρελθόν. Ο χρήστης δεν βλέπει παράθυρο συγκατάθεσης. Αυτό το σενάριο συμβαίνει εάν ο χρήστης έχει ήδη δώσει τη συγκατάθεσή του τουλάχιστον μία φορά στο Microsoft Graph για αυτήν την εφαρμογή ή εάν ο χρήστης αποτελεί μέρος του κεντρικού μισθωτή της εφαρμογής.
Και στα δύο σενάρια, ο φόρτος εργασίας δεν θα πρέπει να ενδιαφέρεται για το αν ο χρήστης έδωσε πλήρη συγκατάθεση για όλες τις εξαρτήσεις (και δεν μπορεί να γνωρίζει σε αυτό το σημείο). Το διακριτικό λήψης έχει το κοινό παρασκηνίου φόρτου εργασίας και μπορεί να χρησιμοποιηθεί για απευθείας κλήση του παρασκηνίου φόρτου εργασίας από το προσκήνιο φόρτου εργασίας.
Βήμα 2: Προσπάθεια πρόσβασης σε εξωτερικές υπηρεσίες
Ο φόρτος εργασίας μπορεί να χρειαστεί πρόσβαση σε υπηρεσίες που απαιτούν έλεγχο ταυτότητας. Για αυτήν την πρόσβαση, πρέπει να εκτελέσειροή
Για την επίλυση αυτού του προβλήματος, είναι ευθύνη του φόρτου εργασίας να μεταδίδει το σφάλμα στο πρόγραμμα-πελάτη κατά την εργασία με άμεσες κλήσεις μεταξύ του προσκηνίου και του παρασκηνίου. Είναι επίσης ευθύνη του φόρτου εργασίας να μεταδίδει το σφάλμα στον υπολογιστή-πελάτη κατά την εργασία με κλήσεις από το Fabric χρησιμοποιώντας τη μετάδοση σφάλματος που περιγράφεται στην επικοινωνία φόρτου εργασίας.
Αφού ο φόρτος εργασίας μεταδίδει το σφάλμα, μπορεί να καλέσει τον acquireAccessToken JavaScript API για να επιλύσει το πρόβλημα συγκατάθεσης ή πολιτικής πρόσβασης υπό όρους και να επαναλάβει τη λειτουργία.
Για αποτυχίες API επιπέδου δεδομένων, ανατρέξτε στο θέμα Χειρισμός ελέγχου ταυτότητας πολλών παραγόντων, Πρόσβαση υπό όρους και επαυξητική συγκατάθεση. Για αποτυχίες API επιπέδου ελέγχου, ανατρέξτε στο θέμα επικοινωνία φόρτου εργασίας.
Παραδείγματα σεναρίων
Ας ρίξουμε μια ματιά σε έναν φόρτο εργασίας που χρειάζεται πρόσβαση σε τρία API Fabric:
Λίστα χώρων εργασίας:
GET https://api.fabric.microsoft.com/v1/workspacesΔημιουργία αποθήκης:
POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehousesΓράψτε σε ένα αρχείο lakehouse:
PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file
Για να μπορέσετε να εργαστείτε με αυτά τα API, το παρασκήνιο φόρτου εργασίας πρέπει να ανταλλάξει διακριτικά για τις ακόλουθες εμβέλειες:
- Για την παράθεση χώρων εργασίας:
https://analysis.windows.net/powerbi/api/Workspace.Read.Allήhttps://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All - Για τη δημιουργία μιας αποθήκης:
https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.Allήhttps://analysis.windows.net/powerbi/api/Item.ReadWrite.All - Για εγγραφή σε ένα αρχείο lakehouse:
https://storage.azure.com/user_impersonation
Σημείωμα
Μπορείτε να βρείτε τις εμβέλειες που απαιτούνται για κάθε API Fabric στο αυτό το άρθρο αναφοράς.
Οι εμβέλειες που αναφέρονται παραπάνω πρέπει να ρυθμιστούν στην εφαρμογή φόρτου εργασίας στην περιοχή δικαιώματα API.
Ας ρίξουμε μια ματιά σε παραδείγματα σεναρίων που ενδέχεται να αντιμετωπίσει ο φόρτος εργασίας.
Παράδειγμα 1
Ας υποθέσουμε ότι το παρασκήνιο φόρτου εργασίας έχει ένα API επιπέδου δεδομένων που λαμβάνει τους χώρους εργασίας του χρήστη και τους επιστρέφει στο πρόγραμμα-πελάτη:
Το προσκήνιο φόρτου εργασίας ζητά ένα διακριτικό χρησιμοποιώντας το JavaScript API.
Το προσκήνιο φόρτου εργασίας καλεί το API παρασκηνίου φόρτου εργασίας για να λάβει τους χώρους εργασίας του χρήστη και επισυνάπτει το διακριτικό στην αίτηση.
Το παρασκήνιο φόρτου εργασίας επικυρώνει το διακριτικό και προσπαθεί να το ανταλλάξει με την απαιτούμενη εμβέλεια (ας υποθέσουμε
https://analysis.windows.net/powerbi/api/Workspace.Read.All).Ο φόρτος εργασίας αποτυγχάνει να ανταλλάξει το διακριτικό με τον καθορισμένο πόρο, επειδή ο χρήστης δεν συναινεί στην πρόσβαση σε αυτόν τον πόρο (ανατρέξτε στο θέμα Κωδικοί σφαλμάτων AADSTS).
Το παρασκήνιο φόρτου εργασίας μεταδίδει το σφάλμα στο προσκήνιο φόρτου εργασίας, καθορίζοντας ότι χρειάζεται συγκατάθεση για αυτόν τον πόρο. Το προσκήνιο φόρτου εργασίας καλεί το
acquireAccessTokenJavaScript API και παρέχειadditionalScopesToConsent:workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})Εναλλακτικά, ο φόρτος εργασίας μπορεί να αποφασίσει να ζητήσει συγκατάθεση για όλες τις στατικές εξαρτήσεις του που έχουν ρυθμιστεί στην εφαρμογή του, επομένως καλεί το JavaScript API και παρέχει
promptFullConsent:workloadClient.auth.acquireAccessToken({promptFullConsent: true}).
Αυτή η κλήση ζητά ένα παράθυρο συγκατάθεσης, ανεξάρτητα από το αν ο χρήστης έχει δώσει τη συγκατάθεσή του σε ορισμένες από τις εξαρτήσεις. Μετά από αυτό, το προσκήνιο φόρτου εργασίας μπορεί να επαναλάβει τη λειτουργία.
Σημείωμα
Εάν η ανταλλαγή διακριτικών εξακολουθεί να αποτυγχάνει σε ένα σφάλμα συγκατάθεσης, αυτό σημαίνει ότι ο χρήστης δεν εκχωρήσει συγκατάθεση. Ο φόρτος εργασίας πρέπει να χειρίζεται τέτοια σενάρια. Για παράδειγμα, ειδοποιήστε τον χρήστη ότι αυτό το API απαιτεί συγκατάθεση και δεν θα λειτουργήσει χωρίς αυτό.
Παράδειγμα 2
Ας υποθέσουμε ότι το παρασκήνιο φόρτου εργασίας πρέπει να αποκτήσει πρόσβαση στο OneLake στο API Δημιουργία στοιχείου (κλήση από το Fabric στον φόρτο εργασίας):
Το προσκήνιο φόρτου εργασίας καλεί το API Δημιουργία στοιχείου JavaScript.
Το παρασκήνιο φόρτου εργασίας λαμβάνει μια κλήση από το Fabric και εξάγει το διακριτικό ανάθεσης και το επικυρώνει.
Ο φόρτος εργασίας προσπαθεί να ανταλλάξει το διακριτικό με
https://storage.azure.com/user_impersonationαλλά αποτυγχάνει, επειδή ο διαχειριστής μισθωτή του ελέγχου ταυτότητας πολλών παραγόντων που ρυθμίζεται από τον χρήστη, ο οποίος απαιτείται για πρόσβαση στην Υπηρεσία αποθήκευσης Azure (ανατρέξτε στο θέμα κωδικών σφαλμάτων AADSTS).Ο φόρτος εργασίας μεταδίδει το σφάλμα μαζί με τις αξιώσεις που επιστρέφονται στο σφάλμα από το Αναγνωριστικό Microsoft Entra στο πρόγραμμα-πελάτη, χρησιμοποιώντας τη μετάδοση σφάλματος που περιγράφεται στην επικοινωνία φόρτου εργασίας.
Το προσκήνιο φόρτου εργασίας καλεί το
acquireAccessTokenJavaScript API και παρέχει αξιώσεις ωςclaimsForConditionalAccessPolicy, όπουclaimsαναφέρεται στους ισχυρισμούς που μεταδίδονται από το παρασκήνιο φόρτου εργασίας:workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})
Μετά από αυτό, ο φόρτος εργασίας μπορεί να επαναλάβει τη λειτουργία.
Χειρισμός σφαλμάτων κατά την αίτηση συγκατάθεσης
Ορισμένες φορές ο χρήστης δεν μπορεί να εκχωρήσει συγκατάθεση για διάφορα σφάλματα. Μετά από μια αίτηση συγκατάθεσης, η απόκριση επιστρέφεται στο URI ανακατεύθυνσης. Στο παράδειγμά μας, αυτός ο κώδικας είναι υπεύθυνος για τον χειρισμό της απόκρισης. (Μπορείτε να το βρείτε στο αρχείο 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();
}
Το προσκήνιο φόρτου εργασίας μπορεί να εξαγάγει τον κωδικό σφάλματος από τη διεύθυνση URL και να τον χειριστεί ανάλογα.
Σημείωμα
Και στα δύο σενάρια (σφάλμα και επιτυχία), ο φόρτος εργασίας πρέπει να κλείνει πάντα αμέσως το παράθυρο, χωρίς λανθάνοντα χρόνου.