處理驗證

驗證類型

擴充功能可以支援一種或多種認證方式。每種認證類型都是不同類型的憑證。 Power Query 中顯示給終端使用者的認證介面，是由擴充套件所支援的憑證類型所驅動。

支援的認證類型清單是作為擴充套件資料來源類型定義的一部分所定義。每個認證值都是帶有特定欄位的紀錄。下表列出每種類型所期望的欄位。除非另有標示，否則所有欄位皆為必填。

認證類型	領域	Description
匿名		匿名（也稱為 `Implicit`）認證類型沒有任何欄位。
OAuth	開始登入	提供啟動 OAuth 流程所需的 URL 與狀態資訊函式。請前往「實作 OAuth Flow 」章節。
	完成登入	這個函數能提取與 OAuth 流程相關的access_token及其他屬性。
	刷新	（可選）從刷新令牌中取得新的存取權杖的函式。
	Logout	（可選）會使使用者目前的存取權杖失效的功能。
	標籤	（可選）一個文字值，讓你可以取代這個 AuthenticationKind 的預設標籤。
Aad	授權URI	`text` 返回 Microsoft Entra ID 授權端點的值或一元函式（例如： `"https://login.microsoftonline.com/common/oauth2/authorize"`）。前往 Microsoft Entra ID 認證區塊。
	Resource	`text` 值或一元函式，回傳你服務的 Microsoft Entra ID 資源值。
	Scope	（可選）`text` 值或一元函式，回傳作為驗證流程一部分的請求範圍清單。多個範圍值應該以空格分隔。作用域值應為作用域名稱，且不應使用應用程式 ID URI（例如： `Data.Read`）。若未提供，則會請求 `user_impersonation` 範圍。
用戶名密碼	用戶名稱標籤	（可選）一個文字值，用來取代憑證介面中使用者名稱文字框的預設標籤。
	密碼標籤	（可選）一個文字值，用來取代憑證介面中密碼文字框的預設標籤。
	標籤	（可選）一個文字值，讓你可以覆寫這個 AuthenticationKind 的預設標籤。
窗戶	用戶名稱標籤	（可選）一個文字值，用來取代憑證介面中使用者名稱文字框的預設標籤。
	密碼標籤	（可選）一個文字值，用來取代憑證介面中密碼文字框的預設標籤。
	標籤	（可選）一個文字值，讓你可以覆寫這個 AuthenticationKind 的預設標籤。
Key	KeyLabel	（可選）一個文字值，用來取代憑證介面中 API Key 文字框的預設標籤。
	標籤	（可選）一個文字值，讓您可以覆寫此 AuthenticationKind 的預設標籤。

以下範例展示了支援 OAuth、金鑰、Windows、BASIC（使用者名稱與密碼）及匿名憑證的連接器的認證紀錄。

Example:

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

取得目前的認證資料

目前的憑證可以透過函 Extension.CurrentCredential 式取得。

可擴展的 M 資料來源函式會自動繼承您擴充功能的憑證範圍。大多數情況下，您不需要明確存取目前的憑證，但也有例外，例如：

以自訂標頭或查詢字串參數傳遞憑證（例如使用 API Key 認證類型時）。
設定 ODBC 或 ADO.NET 擴充的連線字串屬性。
檢查 OAuth 代幣上的自訂屬性。
將憑證作為 OAuth v1 流程的一部分使用。

函式 Extension.CurrentCredential 將回傳一個紀錄物件。它所包含的欄位是特定認證類型的。下表包含詳細資訊。

領域	Description	使用者
認證類型	包含指派給此憑證的認證類型名稱（UsernamePassword、OAuth 等）。	全部
用戶名稱	用戶名稱價值	使用者名稱密碼，Windows
密碼	密碼值。通常與 UsernamePassword 一起使用，但也可用於 Key。	金鑰、使用者名稱密碼、Windows
access_token	OAuth 存取權代幣價值。	OAuth
屬性	包含特定憑證其他自訂屬性的紀錄。通常用於與 OAuth 一起保存其他在認證流程中與 access_token 一起返回的屬性（例如 refresh_token）。	OAuth
Key	API 金鑰值。請注意，密碼欄位中也有鍵值。預設情況下，混搭引擎會將此金鑰插入授權標頭，就像這個值是基本的驗證密碼（無使用者名稱）一樣。如果這種行為不是你想要的，你必須在選項紀錄中指定 ManualCredentials = true 選項。	Key
加密連線	一個邏輯值決定是否需要與資料來源進行加密連線。此值適用於所有認證類型，但僅在資料來源定義中指定 EncryptConnection 時才會設定。	全部

以下程式碼範例存取 API 金鑰的當前憑證，並用它填充自訂標頭（x-APIKey）。

Example:

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數接受一個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 ID 驗證

認證 Aad 類型是針對 Microsoft Entra ID 的 OAuth 專用版本。它使用與內建支援組織帳號驗證的 Power Query 連接器相同的 Microsoft Entra ID 用戶端。更多資訊可參考《設定 Microsoft Entra 以取得自訂連接器快速入門指南》。

備註

如果您為 Microsoft Entra ID 實作自訂的 OAuth 流程，已啟用條件存取的租戶中的使用者在使用 Power BI 服務進行重新整理時可能會遇到問題。這不會影響基於閘道的刷新，但會影響支援 Power BI 服務刷新的認證連接器。使用者在透過 Power BI 服務設定基於網頁的憑證時，可能會遇到使用公共用戶端應用程式的連接器所引發的問題。此流程產生的存取權杖最終會用於與原本用於驗證的電腦（即設定公司網路資料來源憑證使用者的電腦）不同的電腦（即 Azure 資料中心的 Power BI 服務，而非公司網路上的）。內建 Aad 類型透過在 Power BI 服務中設定憑證時使用不同的 Microsoft Entra ID 用戶端來解決這個問題。使用 OAuth 認證型連接器時，此選項無法提供。

大多數連接器都需要為AuthorizationUri和Resource欄位提供數值。兩個欄位都可以是 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 ID，使用共用租戶（無 Azure B2B 支援）。請求 .default 範圍時，會回傳一個包含 Power Query 客戶端應用程式 ID 先前授權所有範圍的令牌。

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 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 的單一登入，請參閱額外連接器功能文章以了解更多。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-26