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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงเรกคอร์ดการรับรองความถูกต้องสําหรับตัวเชื่อมต่อที่สนับสนุนข้อมูลประจําตัว OAuth, คีย์, 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 ส่งกลับออบเจ็กต์เรกคอร์ด ฟิลด์ที่มีอยู่เป็นชนิดการรับรองความถูกต้องเฉพาะ ตารางต่อไปนี้มีรายละเอียด

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

Note

ส่วนขยาย Power Query ได้รับการประเมินในแอปพลิเคชันที่ทํางานบนเครื่องไคลเอ็นต์ ตัวเชื่อมต่อข้อมูล ไม่ควร ใช้ข้อมูลลับในโฟลว์ OAuth เนื่องจากผู้ใช้อาจตรวจสอบส่วนขยายหรือการรับส่งข้อมูลเครือข่ายเพื่อเรียนรู้ข้อมูลลับ ไปที่ คีย์พิสูจน์สําหรับการแลกเปลี่ยนโค้ดโดย RFC ไคลเอ็นต์สาธารณะ OAuth (หรือที่เรียกว่า PKCE) สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับการจัดหาโฟลว์ที่ไม่พึ่งพาข้อมูลลับที่ใช้ร่วมกัน ตัวอย่าง การใช้งานของ โฟลว์นี้สามารถพบได้ในไซต์ GitHub ของเรา

ลายเซ็นฟังก์ชัน OAuth มีสองชุด ได้แก่ ลายเซ็นต้นฉบับที่มีพารามิเตอร์จํานวนน้อยที่สุด และลายเซ็นขั้นสูงที่ยอมรับพารามิเตอร์เพิ่มเติม โฟลว์ OAuth ส่วนใหญ่สามารถใช้งานได้โดยใช้ลายเซ็นต้นฉบับ คุณยังสามารถผสมและจับคู่ประเภทลายเซ็นในการใช้งานของคุณได้ การเรียกใช้ฟังก์ชันจะจับคู่ตามจํานวนพารามิเตอร์ (และชนิด) ชื่อพารามิเตอร์จะไม่ถูกนํามาพิจารณา

ไปที่ ตัวอย่าง GitHub สําหรับรายละเอียดเพิ่มเติม

ลายเซ็น OAuth ดั้งเดิม

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

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

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

Logout = (accessToken) => ...;

ลายเซ็น OAuth ขั้นสูง

หมายเหตุเกี่ยวกับลายเซ็นขั้นสูง:

• ลายเซ็นทั้งหมดยอมรับ clientApplication ค่าเรกคอร์ด ซึ่งสงวนไว้สําหรับการใช้งานในอนาคต
• ลายเซ็นทั้งหมดยอมรับ a dataSourcePath (หรือที่เรียกว่า resourceUrl ในตัวอย่างส่วนใหญ่)
• ฟังก์ชันยอมรับRefresholdCredentialพารามิเตอร์ ซึ่งเป็นพารามิเตอร์ก่อนหน้า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ชนิดการรับรองความถูกต้องเป็นเวอร์ชันเฉพาะของ OAuth สําหรับ Microsoft Entra ID ใช้ไคลเอ็นต์ Microsoft Entra ID เดียวกันกับตัวเชื่อมต่อ Power Query ในตัวที่รองรับการรับรองความถูกต้องของบัญชีองค์กร ข้อมูลเพิ่มเติมสามารถพบได้ใน การกําหนดค่า Microsoft Entra สําหรับ คู่มือเริ่มต้นใช้งานด่วนของตัวเชื่อมต่อแบบกําหนดเอง

Note

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

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 โปรดไปที่บทความ ฟังก์ชันตัวเชื่อมต่อเพิ่มเติม เพื่อเรียนรู้เพิ่มเติม