Χειρισμός ελέγχου ταυτότητας

Είδη ελέγχου ταυτότητας

Μια επέκταση μπορεί να υποστηρίξει ένα ή περισσότερα είδη ελέγχου ταυτότητας. Κάθε είδος ελέγχου ταυτότητας είναι ένας διαφορετικός τύπος διαπιστευτηρίων. Το περιβάλλον εργασίας χρήστη ελέγχου ταυτότητας που εμφανίζεται στους τελικούς χρήστες στο Power Query καθοδηγείται από τον τύπο διαπιστευτηρίων που υποστηρίζει μια επέκταση.

Η λίστα των υποστηριζόμενων τύπων ελέγχου ταυτότητας ορίζεται ως μέρος του ορισμού Είδος προέλευσης δεδομένων μιας επέκτασης. Κάθε τιμή ελέγχου ταυτότητας είναι μια εγγραφή με συγκεκριμένα πεδία. Ο παρακάτω πίνακας παραθέτει τα αναμενόμενα πεδία για κάθε είδος. Όλα τα πεδία απαιτούνται, εκτός εάν επισημαίνεται διαφορετικά.

Είδος ελέγχου ταυτότητας	Πεδίο	Περιγραφή
Ανώνυμο		Το είδος ελέγχου ταυτότητας Ανώνυμο (επίσης ονομάζεται Implicit) δεν διαθέτει πεδία.
OAuth	StartLogin	Συνάρτηση που παρέχει πληροφορίες διεύθυνσης URL και κατάστασης για την εκκίνηση μιας ροής OAuth. Μεταβείτε στην ενότητα Υλοποίηση ροής OAuth .
	FinishLogin	Συνάρτηση που εξάγει τις access_token και άλλες ιδιότητες που σχετίζονται με τη ροή OAuth.
	Ανανέωση	(προαιρετικό) Συνάρτηση που ανακτά ένα νέο διακριτικό πρόσβασης από ένα διακριτικό ανανέωσης.
	Αποσύνδεση	(προαιρετικό) Συνάρτηση που ακυρώνει το τρέχον διακριτικό πρόσβασης του χρήστη.
	Ετικέτα	(προαιρετικό) Μια τιμή κειμένου που σας επιτρέπει να παρακάμψετε την προεπιλεγμένη ετικέτα για αυτή την ιδιότητα AuthenticationKind.
Aad	AuthorizationUri	text value ή μοναδιαία συνάρτηση που επιστρέφει το τελικό σημείο εξουσιοδότησης αναγνωριστικού Microsoft Entra (παράδειγμα: "https://login.microsoftonline.com/common/oauth2/authorize"). Μεταβείτε στην ενότητα Ελέγχου ταυτότητας αναγνωριστικού Microsoft Entra.
	Resource	text value ή μοναδιαία συνάρτηση που επιστρέφει την τιμή πόρου του αναγνωριστικού Entra της Microsoft για την υπηρεσία σας.
	Εμβέλεια	(προαιρετικό) text value ή μοναδιαία συνάρτηση που επιστρέφει τη λίστα των εμβέλειων που θα ζητήσουν ως μέρος της ροής ελέγχου ταυτότητας. Οι τιμές πολλαπλής εμβέλειας πρέπει να διαχωρίζονται με ένα διάστημα. Η τιμή εμβέλειας πρέπει να είναι το όνομα εμβέλειας, χωρίς URI αναγνωριστικού εφαρμογής (παράδειγμα: Data.Read). Όταν δεν παρέχεται, ζητείται η user_impersonation εμβέλεια.
UsernamePassword	UsernameLabel	(προαιρετικό) Μια τιμή κειμένου για αντικατάσταση της προεπιλεγμένης ετικέτας για το πλαίσιο κειμένου Όνομα χρήστη στο περιβάλλον εργασίας χρήστη.
	PasswordLabel	(προαιρετικό) Μια τιμή κειμένου για αντικατάσταση της προεπιλεγμένης ετικέτας για το πλαίσιο κειμένου Κωδικός πρόσβασης στο περιβάλλον εργασίας χρήστη διαπιστευτηρίων.
	Ετικέτα	(προαιρετικό) Μια τιμή κειμένου που σας επιτρέπει να παρακάμψετε την προεπιλεγμένη ετικέτα για αυτή την ιδιότητα AuthenticationKind.
Windows	UsernameLabel	(προαιρετικό) Μια τιμή κειμένου για αντικατάσταση της προεπιλεγμένης ετικέτας για το πλαίσιο κειμένου Όνομα χρήστη στο περιβάλλον εργασίας χρήστη.
	PasswordLabel	(προαιρετικό) Μια τιμή κειμένου για αντικατάσταση της προεπιλεγμένης ετικέτας για το πλαίσιο κειμένου Κωδικός πρόσβασης στο περιβάλλον εργασίας χρήστη διαπιστευτηρίων.
	Ετικέτα	(προαιρετικό) Μια τιμή κειμένου που σας επιτρέπει να παρακάμψετε την προεπιλεγμένη ετικέτα για αυτή την ιδιότητα AuthenticationKind.
Κλειδί	KeyLabel	(προαιρετικό) Μια τιμή κειμένου για την αντικατάσταση της προεπιλεγμένης ετικέτας για το πλαίσιο κειμένου Κλειδί API στο περιβάλλον εργασίας χρήστη διαπιστευτηρίων.
	Ετικέτα	(προαιρετικό) Μια τιμή κειμένου που σας επιτρέπει να παρακάμψετε την προεπιλεγμένη ετικέτα για αυτή την ιδιότητα AuthenticationKind.

Το παρακάτω δείγμα εμφανίζει την εγγραφή Ελέγχου ταυτότητας για μια σύνδεση που υποστηρίζει OAuth, Κλειδί, Windows, Βασικός (όνομα χρήστη και κωδικός πρόσβασης) και ανώνυμα διαπιστευτήρια.

Παράδειγμα:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Anonymous = []
]

Πρόσβαση στα τρέχοντα διαπιστευτήρια

Τα τρέχοντα διαπιστευτήρια μπορούν να ανακτηθούν με χρήση της συνάρτησης Extension.CurrentCredential .

Οι συναρτήσεις προέλευσης δεδομένων M που έχουν ενεργοποιηθεί για επεκτασιμότητα μεταβιβάζονται αυτόματα στην εμβέλεια διαπιστευτηρίων της επέκτασής σας. Στις περισσότερες περιπτώσεις, δεν χρειάζεται να αποκτήσετε ρητή πρόσβαση στα τρέχοντα διαπιστευτήρια, ωστόσο, υπάρχουν εξαιρέσεις, όπως:

• Μεταβίβαση των διαπιστευτηρίων σε μια παράμετρο συμβολοσειράς προσαρμοσμένης κεφαλίδας ή ερωτήματος (όπως όταν χρησιμοποιείτε τον τύπο ελέγχου ταυτότητας κλειδιού API).
• Ορισμός ιδιοτήτων συμβολοσειράς σύνδεσης για επεκτάσεις ODBC ή ADO.NET.
• Έλεγχος προσαρμοσμένων ιδιοτήτων σε ένα διακριτικό OAuth.
• Χρήση των διαπιστευτηρίων ως μέρος μιας ροής OAuth v1.

Η Extension.CurrentCredential συνάρτηση επιστρέφει ένα αντικείμενο εγγραφής. Τα πεδία που περιέχει αφορούν συγκεκριμένο τύπο ελέγχου ταυτότητας. Ο παρακάτω πίνακας περιέχει λεπτομέρειες.

Πεδίο	Περιγραφή	Χρησιμοποιείται από
AuthenticationKind	Περιέχει το όνομα του είδους ελέγχου ταυτότητας που έχει αντιστοιχιστεί σε αυτό το διαπιστευτήριο (UsernamePassword, OAuth και ούτω καθεξής).	Όλα
Username	Τιμή ονόματος χρήστη	UsernamePassword, Windows
Κωδικός πρόσβασης	Τιμή κωδικού πρόσβασης. Συνήθως χρησιμοποιείται με το UsernamePassword, αλλά ορίζεται επίσης ως Κλειδί.	Κλειδί, Όνομα χρήστηΚωδικός πρόσβασης, Windows
access_token	Τιμή διακριτικού πρόσβασης OAuth.	OAuth
Ιδιότητες	Μια εγγραφή που περιέχει άλλες προσαρμοσμένες ιδιότητες για ένα δεδομένο διαπιστευτήριο. Συνήθως χρησιμοποιείται με OAuth για την αποθήκευση άλλων ιδιοτήτων (όπως η refresh_token) που επιστρέφονται με το access_token κατά τη διάρκεια της ροής ελέγχου ταυτότητας.	OAuth
Κλειδί	Η τιμή κλειδιού API. Σημειώστε ότι η τιμή κλειδιού είναι επίσης διαθέσιμη και στο πεδίο Κωδικός πρόσβασης. Από προεπιλογή, η μηχανή συνδυασμού δεδομένων εισάγει αυτό το κλειδί σε μια κεφαλίδα εξουσιοδότησης σαν αυτή η τιμή να ήταν ένας βασικός κωδικός πρόσβασης ελέγχου ταυτότητας (χωρίς όνομα χρήστη). Εάν αυτός ο τύπος συμπεριφοράς δεν είναι αυτός που θέλετε, πρέπει να καθορίσετε την επιλογή ManualCredentials = true στην εγγραφή επιλογών.	Κλειδί
EncryptConnection	Μια λογική τιμή που προσδιόρισε εάν θα απαιτείται κρυπτογραφημένη σύνδεση στην προέλευση δεδομένων. Αυτή η τιμή είναι διαθέσιμη για όλα τα είδη ελέγχου ταυτότητας, αλλά ορίζεται μόνο εάν έχει καθοριστεί η EncryptConnection στον ορισμό προέλευσης δεδομένων.	Όλα

Το ακόλουθο δείγμα κώδικα αποκτά πρόσβαση στα τρέχοντα διαπιστευτήρια για ένα κλειδί API και το χρησιμοποιεί για να συμπληρώσει μια προσαρμοσμένη κεφαλίδα (x-APIKey).

Παράδειγμα:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

Υλοποίηση μιας ροής OAuth

Ο τύπος ελέγχου ταυτότητας OAuth επιτρέπει σε μια επέκταση να υλοποιεί προσαρμοσμένη λογική για την υπηρεσία της. Για να γίνει αυτό, μια επέκταση παρέχει συναρτήσεις για StartLogin το (επιστρέφοντας το URI εξουσιοδότησης για εκκίνηση της ροής OAuth) και FinishLogin (την ανταλλαγή του κωδικού εξουσιοδότησης για ένα διακριτικό πρόσβασης). Οι επεκτάσεις μπορούν προαιρετικά να υλοποιήσουν Refresh (ανταλλάσσοντας ένα διακριτικό ανανέωσης για ένα νέο διακριτικό πρόσβασης) και Logout (λήξη της τρέχουσας ανανέωσης και διακριτικών πρόσβασης).

Σημείωμα

Οι επεκτάσεις Power Query αξιολογούνται σε εφαρμογές που εκτελούνται σε υπολογιστές-πελάτες. Οι συνδέσεις δεδομένων δεν πρέπει να χρησιμοποιούν εμπιστευτικά μυστικά στις ροές τους OAuth, καθώς οι χρήστες ενδέχεται να ελέγξουν την επέκταση ή την κίνηση δικτύου για να μάθουν τον μυστικό κωδικό. Μεταβείτε στην επιλογή Κλειδί επαλήθευσης για Exchange κώδικα από RFC δημόσιων πελατών OAuth (γνωστό και ως PKCE) για περισσότερες λεπτομέρειες σχετικά με την παροχή ροών που δεν βασίζονται σε κοινόχρηστα μυστικά. Μπορείτε να βρείτε ένα δείγμα υλοποίησης αυτής της ροής στην τοποθεσία μας στο GitHub.

Υπάρχουν δύο σύνολα υπογραφών συναρτήσεων OAuth: η αρχική υπογραφή που περιέχει έναν ελάχιστο αριθμό παραμέτρων και μια σύνθετη υπογραφή που αποδέχεται περισσότερες παραμέτρους. Οι περισσότερες ροές OAuth μπορούν να υλοποιηθούν χρησιμοποιώντας τις αρχικές υπογραφές. Μπορείτε επίσης να αναμίξετε και να αντιστοιχήσετε τύπους υπογραφών στην υλοποίησή σας. Οι κλήσεις συναρτήσεων είναι αντιστοιχίες με βάση τον αριθμό των παραμέτρων (και τους τύπους τους). Τα ονόματα παραμέτρων δεν λαμβάνονται υπόψη.

Μεταβείτε στο δείγμα GitHub για περισσότερες λεπτομέρειες.

Αρχικές υπογραφές OAuth

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

Σύνθετες υπογραφές OAuth

Σημειώσεις σχετικά με τις σύνθετες υπογραφές:

• Όλες οι υπογραφές αποδέχονται μια clientApplication τιμή εγγραφής, η οποία είναι δεσμευμένη για μελλοντική χρήση.
• Όλες οι υπογραφές αποδέχονται ένα dataSourcePath (γνωστό και ως resourceUrl στα περισσότερα δείγματα).
• Η Refresh συνάρτηση αποδέχεται μια oldCredential παράμετρο, η οποία είναι η προηγούμενη record που επιστρέφεται από FinishLogin τη συνάρτηση (ή την προηγούμενη κλήση στο Refresh).

StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

Έλεγχος ταυτότητας αναγνωριστικού Microsoft Entra

Το Aad είδος ελέγχου ταυτότητας είναι μια εξειδικευμένη έκδοση του OAuth για το αναγνωριστικό Microsoft Entra. Χρησιμοποιεί το ίδιο πρόγραμμα-πελάτη αναγνωριστικού Microsoft Entra με τις ενσωματωμένες συνδέσεις Power Query που υποστηρίζουν έλεγχο ταυτότητας εταιρικού λογαριασμού. Μπορείτε να βρείτε περισσότερες πληροφορίες στο θέμα Ρύθμιση παραμέτρων του Microsoft Entra για έναν οδηγό γρήγορης εκκίνησης προσαρμοσμένης σύνδεσης.

Σημείωμα

Εάν υλοποιήσετε τη δική σας ροή OAuth για το Αναγνωριστικό Microsoft Entra, οι χρήστες που έχουν ενεργοποιήσει την Πρόσβαση υπό όρους για τον μισθωτή τους ενδέχεται να αντιμετωπίσουν προβλήματα κατά την ανανέωση με χρήση της υπηρεσίας Power BI. Αυτό δεν θα επηρεάσει την ανανέωση βάσει πύλης, αλλά θα επηρεάσει μια πιστοποιημένη σύνδεση που υποστηρίζει ανανέωση από την υπηρεσία Power BI. Οι χρήστες ενδέχεται να αντιμετωπίσουν ένα πρόβλημα που προκύπτει από τη σύνδεση που χρησιμοποιεί μια δημόσια εφαρμογή προγράμματος-πελάτη κατά τη ρύθμιση παραμέτρων διαπιστευτηρίων που βασίζονται στο Web μέσω της υπηρεσίας Power BI. Το διακριτικό πρόσβασης που δημιουργείται από αυτήν τη ροή θα χρησιμοποιηθεί τελικά σε έναν διαφορετικό υπολογιστή (δηλαδή, στην υπηρεσία Power BI σε ένα κέντρο δεδομένων Azure, όχι στο εταιρικό δίκτυο) από εκείνον που χρησιμοποιήθηκε για τον αρχικό έλεγχο ταυτότητας (δηλαδή, στον υπολογιστή του χρήστη που ρυθμίζει τα διαπιστευτήρια προέλευσης δεδομένων στο εταιρικό δίκτυο). Ο ενσωματωμένος Aad τύπος λειτουργεί γύρω από αυτό το πρόβλημα χρησιμοποιώντας ένα διαφορετικό πρόγραμμα-πελάτη Microsoft Entra ID κατά τη ρύθμιση παραμέτρων διαπιστευτηρίων στην υπηρεσία Power BI. Αυτή η επιλογή δεν θα είναι διαθέσιμη για συνδέσεις που χρησιμοποιούν το OAuth είδος ελέγχου ταυτότητας.

Οι περισσότερες συνδέσεις πρέπει να παρέχουν τιμές για τα AuthorizationUri πεδία και Resource . Και τα δύο πεδία μπορεί να είναι text τιμές ή μια συνάρτηση ενός ορίσματος που επιστρέφει μια text value.

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Οι συνδέσεις που χρησιμοποιούν ένα αναγνωριστικό που βασίζεται σε Uri δεν χρειάζεται να παρέχουν μια Resource τιμή. Από προεπιλογή, η τιμή ισούται με τη ριζική διαδρομή της παραμέτρου Uri της σύνδεσης. Εάν ο πόρος Αναγνωριστικού Microsoft Entra της προέλευσης δεδομένων είναι διαφορετικός από την τιμή τομέα (για παράδειγμα, χρησιμοποιεί GUID), τότε πρέπει να παρασχεθεί μια Resource τιμή.

Δείγματα τύπου ελέγχου ταυτότητας Aad

Στην ακόλουθη περίπτωση, η προέλευση δεδομένων υποστηρίζει καθολικό cloud Microsoft Entra ID με χρήση του κοινού μισθωτή (χωρίς υποστήριξη Azure B2B). Η αίτηση για την εμβέλεια .default επιστρέφει ένα διακριτικό με όλες τις προηγουμένως εξουσιοδοτημένες εμβέλειες για το αναγνωριστικό εφαρμογής προγράμματος-πελάτη Power Query.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Στην ακόλουθη περίπτωση, η προέλευση δεδομένων υποστηρίζει τον εντοπισμό μισθωτή με βάση το OpenID Connect (OIDC) ή παρόμοιο πρωτόκολλο. Αυτή η δυνατότητα επιτρέπει στη σύνδεση να προσδιορίζει το σωστό τελικό σημείο Microsoft Entra ID που θα χρησιμοποιηθεί βάσει μίας ή περισσότερων παραμέτρων στη διαδρομή προέλευσης δεδομένων. Αυτή η προσέγγιση δυναμικού εντοπισμού επιτρέπει στη σύνδεση να υποστηρίζει το Azure B2B.

// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication.", [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication.");

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Microsoft Entra ID resource value for your service - Guid or URL
        Scope = ".default"
    ]
]

Άλλοι τύποι ελέγχου ταυτότητας

Για πληροφορίες σχετικά με άλλους τύπους ελέγχου ταυτότητας που δεν καλύπτονται σε αυτό το άρθρο, όπως καθολική σύνδεση που βασίζεται στο Kerberos, επισκεφθείτε το άρθρο πρόσθετες λειτουργίες σύνδεσης για να μάθετε περισσότερα.