處理驗證

發行項
12/04/2024

驗證類型

擴充功能可以支援一或多種驗證。每個驗證種類都是不同類型的認證。 Power Query 中向使用者顯示的驗證 UI 是由延伸模組支援的認證類型所驅動。

支援的驗證類型清單會定義為延伸模組數據源種類定義的一部分。每個驗證值都是具有特定欄位的記錄。下表列出每種類型的預期欄位。除非另有標記，否則所有欄位都是必要欄位。

驗證種類	欄位	描述
匿名		匿名（也稱為 `Implicit`）驗證種類沒有任何欄位。
OAuth	StartLogin	提供啟動 OAuth 流程之 URL 和狀態資訊的函式。移至 [ 實作 OAuth 流程 ] 區段。
	FinishLogin	擷取與 OAuth 流程相關的access_token和其他屬性的函式。
	Refresh	（選擇性）從重新整理令牌擷取新存取令牌的函式。
	Logout	（選擇性）使用戶目前存取令牌失效的函式。
	標籤	（選擇性）文字值，可讓您覆寫此 AuthenticationKind 的默認標籤。
Aad	AuthorizationUri	`text` 會傳回Microsoft Entra ID 授權端點的 value 或一元函式（範例： `"https://login.microsoftonline.com/common/oauth2/authorize"`）。移至 [Microsoft Entra ID 驗證 ] 區段。
	資源	`text` value 或 unary 函式，會傳回您服務的 Microsoft Entra ID 資源值。
	範圍	（選擇性）`text`值或一元函式，傳回範圍清單以作為驗證流程的一部分要求。多個範圍值應該以空格分隔。範圍值應該是範圍名稱，不含應用程式標識碼 URI（例如： `Data.Read`）。未提供時， `user_impersonation` 會要求範圍。
UsernamePassword	UsernameLabel	（選擇性）要取代認證 UI 上 [使用者名稱] 文字框的預設標籤的文字值。
	PasswordLabel	（選擇性）文字值，用來取代認證 UI 上 [密碼] 文字框的預設標籤。
	標籤	（選擇性）文字值，可讓您覆寫此 AuthenticationKind 的默認標籤。
Windows	UsernameLabel	（選擇性）要取代認證 UI 上 [使用者名稱] 文字框的預設標籤的文字值。
	PasswordLabel	（選擇性）文字值，用來取代認證 UI 上 [密碼] 文字框的預設標籤。
	標籤	（選擇性）文字值，可讓您覆寫此 AuthenticationKind 的默認標籤。
機碼	KeyLabel	（選擇性）文字值，用來取代認證 UI 上 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 等等）。	全部
使用者名稱	用戶名稱值	UsernamePassword、Windows
密碼	密碼值。通常搭配 UsernamePassword 使用，但也會針對 Key 進行設定。	Key、UsernamePassword、Windows
access_token	OAuth 存取令牌值。	OAuth
屬性	包含指定認證之其他自定義屬性的記錄。通常與 OAuth 搭配使用，以在驗證流程期間以access_token傳回的其他屬性（例如refresh_token）。	OAuth
機碼	API 金鑰值。請注意，金鑰值也可以在 [密碼] 欄位中使用。根據預設，混搭引擎會在 Authorization 標頭中插入此密鑰，就好像此值是基本身份驗證密碼（沒有使用者名稱）。如果這種類型的行為不是您想要的行為，您必須在選項記錄中指定 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 流程中使用機密秘密，因為使用者可以檢查延伸模組或網路流量來瞭解秘密。如需提供不依賴共用秘密之流程的進一步詳細數據，請移至 OAuth 公用用戶端 RFC （也稱為 PKCE）的程式代碼交換證明密鑰。您可以在我們的 GitHub 網站上找到此流程的範例實作。

OAuth 函式簽章有兩組：原始簽章，其中包含最少的參數數目，以及接受更多參數的進階簽章。大部分的 OAuth 流程都可以使用原始簽章來實作。您也可以在實作中混合和比對簽章類型。函式呼叫會根據參數數目（及其類型）進行比對。參數名稱不會納入考慮。

如需詳細資訊，請移至 GitHub 範例。

原始 OAuth 簽章

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

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

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

Logout = (accessToken) => ...;

進階 OAuth 簽章

進階簽章的相關注意事項：

所有簽章都接受 clientApplication 記錄值，保留供日後使用。
所有簽章都接受（dataSourcePath也稱為大多數範例中）。resourceUrl
函Refresh式會接受參數，這是您FinishLogin函式所傳回的上record一個 oldCredential 參數（或先前呼叫的 Refresh）。

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

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

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

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

Microsoft Entra ID 驗證

驗證 Aad 種類是適用於 Microsoft Entra ID 的特殊 OAuth 版本。它會使用與支援組織帳戶驗證的內建 Power Query 連接器相同的Microsoft Entra ID 用戶端。如需詳細資訊，請參閱設定自定義連接器的 Microsoft Entra 快速入門指南。

注意

如果您針對 Microsoft Entra ID 實作自己的 OAuth 流程，則為租使用者啟用條件式存取的使用者在使用 Power BI 服務重新整理時可能會遇到問題。這不會影響閘道型重新整理，但會影響支援從 Power BI 服務重新整理的認證連接器。透過 Power BI 服務設定 Web 型認證時，使用者可能會遇到連接器使用公用用戶端應用程式所導致的問題。此流程所產生的存取令牌最終將用於不同的計算機上（也就是 Azure 資料中心的 Power BI 服務，而不是公司網路上的存取令牌），而不是原先用來驗證的存取令牌（也就是在公司網路上設定數據源認證的用戶計算機）。內建Aad類型可在 Power BI 服務中設定認證時，使用不同的Microsoft Entra ID 用戶端來解決此問題。這個選項不適用於使用 OAuth 驗證類型的連接器。

大部分連接器都需要提供和 Resource 欄位的值AuthorizationUri。這兩個字段可以是 text 值，或傳回的單一 text value自變數函式。

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

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "44445555-eeee-6666-ffff-7777aaaa8888"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

使用 URI 型識別碼的連接器不需要提供 Resource 值。根據預設，此值等於連接器 Uri 參數的根路徑。如果數據源的Microsoft Entra ID 資源與定義域值不同（例如，它會使用 GUID）， Resource 則必須提供值。

Aad 驗證種類範例

在下列情況下，數據源使用通用租用戶支援全域雲端Microsoft Entra標識碼（不支援 Azure B2B）。要求 .default 範圍會傳回具有 Power Query 用戶端應用程式識別碼所有先前授權範圍的令牌。

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "44445555-eeee-6666-ffff-7777aaaa8888", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

在下列情況下，數據源支援以 OpenID Connect （OIDC）或類似通訊協定為基礎的租使用者探索。這項功能可讓連接器根據數據源路徑中的一或多個參數，判斷要使用的正確Microsoft Entra標識符端點。此動態探索方法可讓連接器支援 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 型單一登錄，請流覽其他連接器功能文章以深入瞭解。

共用方式為