การจัดการการรับรองความถูกต้อง

ชนิดของการรับรองความถูกต้อง

ส่วนขยายสามารถสนับสนุนการรับรองความถูกต้องอย่างน้อยหนึ่งชนิด การรับรองความถูกต้องแต่ละประเภทเป็นข้อมูลประจําตัวชนิดที่แตกต่างกัน UI การรับรองความถูกต้องที่แสดงให้กับผู้ใช้ปลายทางใน Power Query ถูกควบคุมโดยประเภทของข้อมูลประจําตัวที่ส่วนขยายสนับสนุน

รายการของชนิดการรับรองความถูกต้องที่ได้รับการสนับสนุนจะถูกกําหนดเป็นส่วนหนึ่งของข้อกําหนดชนิดแหล่งข้อมูลของส่วนขยาย ค่าการรับรองความถูกต้องแต่ละค่าเป็นระเบียนที่มีเขตข้อมูลที่ระบุ ตารางต่อไปนี้แสดงรายการเขตข้อมูลที่คาดไว้สําหรับแต่ละชนิด จําเป็นต้องกรอกข้อมูลทั้งหมด เว้นแต่จะมีการทําเครื่องหมายเป็นอย่างอื่น

ชนิดของการรับรองความถูกต้อง	เขตข้อมูล	คำอธิบาย
ไม่ระบุชื่อ		ชนิดการรับรองความถูกต้องแบบไม่ระบุชื่อ (หรือที่เรียกว่า Implicit) ไม่มีเขตข้อมูลใดๆ
OAuth	StartLogin	ฟังก์ชันที่ให้ข้อมูล URL และสถานะสําหรับการเริ่มต้นโฟลว์ OAuth ไปที่ส่วน การใช้โฟลว์ OAuth
	FinishLogin	ฟังก์ชันที่แยก access_token และคุณสมบัติอื่น ๆ ที่เกี่ยวข้องกับโฟลว์ OAuth
	รีเฟรช	(ไม่บังคับ) ฟังก์ชันที่เรียกใช้โทเค็นการเข้าถึงใหม่จากโทเค็นการรีเฟรช
	ออกจากระบบ	(ไม่บังคับ) ฟังก์ชันที่ทําให้โทเค็นการเข้าถึงปัจจุบันของผู้ใช้ไม่ถูกต้อง
	ป้ายชื่อ	(ไม่บังคับ) ค่าข้อความที่ช่วยให้คุณสามารถแทนที่ป้ายชื่อเริ่มต้นสําหรับ AuthenticationKind นี้
Aad	AuthorizationUri	text value หรือ unary function ที่ส่งกลับจุดสิ้นสุดการให้สิทธิ์รหัส Microsoft Entra (ตัวอย่าง: "https://login.microsoftonline.com/common/oauth2/authorize") ไปที่ส่วน การรับรองความถูกต้องของ Microsoft Entra ID
	Resource	text value หรือ unary function ที่ส่งกลับค่าทรัพยากร Microsoft Entra ID สําหรับบริการของคุณ
	ขอบเขต	(ไม่บังคับ) text value หรือ unary function ที่แสดงรายการขอบเขตเพื่อขอเป็นส่วนหนึ่งของโฟลว์การรับรองความถูกต้อง ค่าขอบเขตหลายค่าควรคั่นด้วยช่องว่าง ค่าขอบเขตควรเป็นชื่อขอบเขต โดยไม่มี URI ID แอปพลิเคชัน (ตัวอย่าง: Data.Read) เมื่อไม่ได้ระบุ user_impersonation ขอบเขตจะถูกร้องขอ
UsernamePassword	UsernameLabel	(ไม่บังคับ) ค่าข้อความที่จะแทนที่ป้ายชื่อเริ่มต้นสําหรับ กล่องข้อความชื่อผู้ใช้ บน UI ข้อมูลประจําตัว
	PasswordLabel	(ไม่บังคับ) ค่าข้อความเพื่อแทนที่ป้ายชื่อเริ่มต้นสําหรับ กล่องข้อความ รหัสผ่าน บน UI ข้อมูลประจําตัว
	ป้ายชื่อ	(ไม่บังคับ) ค่าข้อความที่ช่วยให้คุณสามารถแทนที่ป้ายชื่อเริ่มต้นสําหรับ AuthenticationKind นี้
Windows	UsernameLabel	(ไม่บังคับ) ค่าข้อความที่จะแทนที่ป้ายชื่อเริ่มต้นสําหรับ กล่องข้อความชื่อผู้ใช้ บน UI ข้อมูลประจําตัว
	PasswordLabel	(ไม่บังคับ) ค่าข้อความเพื่อแทนที่ป้ายชื่อเริ่มต้นสําหรับ กล่องข้อความ รหัสผ่าน บน UI ข้อมูลประจําตัว
	ป้ายชื่อ	(ไม่บังคับ) ค่าข้อความที่ช่วยให้คุณสามารถแทนที่ป้ายชื่อเริ่มต้นสําหรับ AuthenticationKind นี้
Key	KeyLabel	(ไม่บังคับ) ค่าข้อความที่จะแทนที่ป้ายชื่อเริ่มต้นสําหรับ กล่องข้อความ API Key บน UI ข้อมูลประจําตัว
	ป้ายชื่อ	(ไม่บังคับ) ค่าข้อความที่ช่วยให้คุณสามารถแทนที่ป้ายชื่อเริ่มต้นสําหรับ AuthenticationKind นี้

ตัวอย่างต่อไปนี้แสดงระเบียนการรับรองความถูกต้องสําหรับตัวเชื่อมต่อที่สนับสนุน OAuth, Key, Windows, Basic (ชื่อผู้ใช้และรหัสผ่าน) และข้อมูลประจําตัวแบบไม่ระบุชื่อ

ตัวอย่าง:

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 และอื่นๆ)	All
Username	ค่าชื่อผู้ใช้	UsernamePassword, Windows
รหัสผ่าน	ค่ารหัสผ่าน โดยทั่วไปใช้กับ UsernamePassword แต่ก็ตั้งค่าสําหรับ Key ด้วย	Key, UsernamePassword, Windows
access_token	ค่าโทเค็นการเข้าถึง OAuth	OAuth
คุณสมบัติ	ระเบียนที่ประกอบด้วยคุณสมบัติแบบกําหนดเองอื่น ๆ สําหรับข้อมูลประจําตัวที่กําหนด โดยทั่วไปใช้กับ OAuth เพื่อจัดเก็บคุณสมบัติอื่น ๆ (เช่น refresh_token) ที่ส่งกลับมากับ access_token ในระหว่างโฟลว์การรับรองความถูกต้อง	OAuth
Key	ค่าคีย์ API โปรดทราบว่าค่าคีย์จะพร้อมใช้งานในเขตข้อมูล Password ด้วยเช่นกัน ตามค่าเริ่มต้น กลไกจัดการ Mashup จะแทรกคีย์นี้ในส่วนหัว Authorization ราวกับว่าค่านี้เป็นรหัสผ่านการรับรองความถูกต้องพื้นฐาน (โดยไม่มีชื่อผู้ใช้) ถ้าลักษณะการทํางานชนิดนี้ไม่ใช่สิ่งที่คุณต้องการ คุณต้องระบุตัวเลือก ManualCredentials = true ในเรกคอร์ดตัวเลือก	Key
EncryptConnection	ค่าตรรกะที่กําหนดว่าต้องการการเชื่อมต่อที่เข้ารหัสลับไปยังแหล่งข้อมูลหรือไม่ ค่านี้จะพร้อมใช้งานสําหรับชนิดการรับรองความถูกต้องทั้งหมด แต่จะถูกตั้งค่าก็ต่อเมื่อมีการระบุ EncryptConnection ในข้อกําหนดของแหล่งข้อมูล	All

ตัวอย่างรหัสต่อไปนี้เข้าถึงข้อมูลประจําตัวปัจจุบันสําหรับคีย์ 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 ของพวกเขา เนื่องจากผู้ใช้อาจตรวจสอบปริมาณการใช้งานส่วนขยายหรือเครือข่ายเพื่อเรียนรู้ข้อมูลลับ ไปที่ Proof Key สําหรับ Exchange Code โดย OAuth Public Clients 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ยอมรับพารามิเตอร์ ซึ่งเป็นค่าก่อนหน้าrecordที่ฟังก์ชันของคุณFinishLoginส่งกลับ (หรือการเรียกก่อนหน้าไปยัง RefresholdCredential )

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

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

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

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

การรับรองความถูกต้องของ Microsoft Entra ID

ชนิด Aad การรับรองความถูกต้องเป็น OAuth เวอร์ชันพิเศษสําหรับ Microsoft Entra ID ซึ่งใช้ไคลเอ็นต์ Microsoft Entra ID เดียวกันกับตัวเชื่อมต่อ Power Query ที่มีอยู่ภายในที่สนับสนุนการรับรองความถูกต้องบัญชีองค์กร สามารถดูข้อมูลเพิ่มเติมได้ใน คู่มือเริ่มต้นใช้งานด่วนการกําหนดค่า Microsoft Entra สําหรับตัวเชื่อมต่อ แบบกําหนดเอง

หมายเหตุ

ถ้าคุณใช้โฟลว์ OAuth ของคุณเองสําหรับ Microsoft Entra ID ผู้ใช้ที่เปิดใช้งานการเข้าถึงแบบมีเงื่อนไขสําหรับผู้เช่าของพวกเขาอาจพบปัญหาเมื่อรีเฟรชโดยใช้บริการของ Power BI การดําเนินการนี้จะไม่ส่งผลกระทบต่อการรีเฟรชตามเกตเวย์ แต่จะส่งผลกระทบต่อตัวเชื่อมต่อที่ได้รับการรับรองที่สนับสนุนการรีเฟรชจากบริการของ Power BI ผู้ใช้อาจพบปัญหาที่เกิดจากตัวเชื่อมต่อโดยใช้แอปพลิเคชันไคลเอ็นต์สาธารณะเมื่อกําหนดค่าข้อมูลประจําตัวบนเว็บผ่านบริการของ Power BI โทเค็นการเข้าถึงที่สร้างขึ้นโดยโฟลว์นี้จะถูกใช้บนคอมพิวเตอร์เครื่องอื่นในท้ายที่สุด (นั่นคือ บริการของ Power BI คอมพิวเตอร์ของผู้ใช้ที่กําหนดค่าข้อมูลประจําตัวของแหล่งข้อมูลบนเครือข่ายของบริษัท) ชนิดที่มีอยู่ภายใน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 ID ของแหล่งข้อมูลแตกต่างจากค่าโดเมน (ตัวอย่างเช่น ใช้ GUID) Resource จะต้องระบุค่า

ตัวอย่างชนิดการรับรองความถูกต้อง Aad

ในกรณีต่อไปนี้ แหล่งข้อมูลสนับสนุนรหัส Microsoft Entra บนระบบคลาวด์ส่วนกลางโดยใช้ผู้เช่าทั่วไป (ไม่มีการสนับสนุน Azure B2B) การร้องขอ ขอบเขต .default จะส่งกลับโทเค็นที่มีขอบเขตที่ได้รับอนุญาตก่อนหน้านี้ทั้งหมดสําหรับ ID แอปพลิเคชันไคลเอ็นต์ 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 โปรดเยี่ยมชม บทความฟังก์ชัน การทํางานของตัวเชื่อมต่อเพิ่มเติมเพื่อเรียนรู้เพิ่มเติม