ใช้โฟลว์การให้สิทธิ์โดยนัยของ OAuth 2.0 ภายในพอร์ทัลของคุณ

  • บทความ
  • 2 นาทีในการอ่าน

คุณลักษณะนี้ช่วยให้ลูกค้าสามารถโทรจากฝั่งไคลเอ็นต์ไปยัง API ภายนอก และรักษาความปลอดภัยโดยใช้โฟลว์การให้สิทธิ์โดยนัยของ OAuth ได้ โดยจะให้จุดสิ้นสุดที่จะรับโทเค็นการเข้าถึงที่มีความปลอดภัยที่จะมีข้อมูลประจำตัวของผู้ใช้ที่จะใช้สำหรับการตรวจสอบโฟลว์การให้สิทธิ์โดยนัยของ OAuth 2.0 ดังต่อไปนี้ของ API ภายนอก ข้อมูลประจำตัวของผู้ใช้ในของผู้ใช้ที่ลงชื่อเข้าใช้จะถูกส่งผ่านไปในลักษณะที่ปลอดภัยเพื่อเรียก AJAX ภายนอก ซึ่งไม่เพียงแต่ช่วยให้นักพัฒนาสามารถส่งบริบทการรับรองความถูกต้องแล้ว แต่จะยังช่วยให้ผู้ใช้รักษาความปลอดภัยให้กับ API ของพวกเขาโดยใช้กลไกนี้

หมายเหตุ

สำหรับแนวทางปฏิบัติที่ดีที่สุดด้านความปลอดภัย ขอแนะนำให้ใช้ ใบรับรองที่กำหนดเอง สำหรับขั้นตอนการให้สิทธิ์โดยนัยของ OAuth 2.0 การใช้โฟลว์การให้สิทธิ์โดยนัยโดยไม่มีใบรับรองที่กำหนดเอง จะไม่ได้รับการสนับสนุนในที่สุด

โฟลว์การให้สิทธิ์โดยนัยของ OAuth 2.0 สนับสนุนจุดสิ้นสุดที่ไคลเอนต์สามารถเรียกเพื่อรับโทเค็นรหัส มีการใช้จุดสิ้นสุดสองรายการสำหรับวัตถุประสงค์นี้: อนุญาต และ โทเค็น

รายละเอียดจุดสิ้นสุดที่อนุญาต

URL สำหรับจุดสิ้นสุดที่อนุญาตคือ: <portal_url>/_services/auth/authorize จุดสิ้นสุดที่อนุญาตสนับสนุนพารามิเตอร์ต่อไปนี้:

พารามิเตอร์ จำเป็นหรือไม่ คำอธิบาย
client_id ได้ สตริงที่ถูกส่งผ่านเมื่อทำการเรียกไปยังจุดสิ้นสุดที่อนุญาต คุณต้องให้แน่ใจว่ารหัสไคลเอนต์ได้รับการ ลงทะเบียนกับพอร์ทัลแล้ว มิฉะนั้น ข้อผิดพลาดจะแสดงขึ้น รหัสไคลเอนต์จะถูกเพิ่มในการอ้างสิทธิ์ในโทเค็นเป็นพารามิเตอร์ aud และ appid และไคลเอนต์สามารถใช้เพื่อตรวจสอบว่าโทเค็นที่ส่งคืนนั้นสำหรับแอปของรายการเหล่านั้นหรือไม่
ความยาวสูงสุด 36 อักขระ รองรับเฉพาะอักขระตัวอักษรผสมตัวเลขและยัติภังค์
redirect_uri ได้ URL ของพอร์ทัลที่สามารถส่งและรับการตอบสนองต่อการรับรองความถูกต้อง คุณจะต้องลงทะเบียนสำหรับ client_id เฉพาะที่ใช้ในการโทร และควรมีค่าที่เหมือนกันทุกประการกับที่ลงทะเบียนไว้
สถานะ ไม่ ค่าที่รวมอยู่ในการร้องขอที่ส่งคืนในการตอบสนองโทเค็น ซึ่งสามารถเป็นสตริงของเนื้อหาใด ๆ ที่คุณต้องการใช้ โดยปกติ ค่าที่ไม่ซ้ำกันที่สร้างขึ้นแบบสุ่มจะถูกใช้เพื่อป้องกันการโจมตีปลอมของการร้องขอข้ามไซต์
ความยาวสูงสุด 20 อักขระ
nonce ไม่ ค่าสตริงที่ถูกส่งโดยไคลเอนต์ที่อยู่ในโทเค็นรหัสที่เป็นผลลัพธ์เป็นการอ้างสิทธิ์ จากนั้นไคลเอนต์สามารถตรวจสอบค่านี้เพื่อลดปัญหาการโจมตีการเล่นโทเค็นซ้ำ ความยาวสูงสุด 20 อักขระ
response_type ไม่ พารามิเตอร์นี้สนับสนุนเฉพาะ token เป็นค่า ซึ่งช่วยให้แอปของคุณสามารถรับโทเค็นการเข้าถึงจากจุดสิ้นสุดที่อนุญาตทันทีโดยไม่ต้องทำการร้องขอครั้งที่สองไปยังจุดสิ้นสุดที่อนุญาต

การตอบสนองที่เสร็จเรียบร้อยแล้ว

จุดสิ้นสุดที่อนุญาตส่งคืนค่าต่อไปนี้ใน URL การตอบสนองโดยเป็นส่วนย่อย:

  • โทเค็น: โทเค็นจะถูกส่งคืนเป็น JSON Web Token (JWT) ที่ลงชื่อโดยคีย์ส่วนตัวของพอร์ทัลแบบดิจิทัล
  • สถานะ: ถ้าพารามิเตอร์สถานะรวมอยู่ในคำขอ ค่าเดียวกันควรจะปรากฏในการตอบสนอง แอปควรตรวจสอบว่าค่าสถานะในการร้องขอและการตอบสนองนั้นเหมือนกัน
  • expires_in: ระยะเวลาที่โทเค็นการเข้าถึงนั้นใช้ได้ (เป็นวินาที)

ตัวอย่างเช่น การตอบสนองที่เสร็จเรียบร้อยแล้วมีลักษณะดังนี้:

GET https://aadb2cplayground.azurewebsites.net/#token=eyJ0eXAiOiJKV1QiLCJhbGciOI1NisIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q&expires_in=3599&state=arbitrary_data_you_sent_earlier

การตอบสนองข้อผิดพลาด

ข้อผิดพลาดในจุดสิ้นสุดที่อนุญาตจะส่งคืนเป็นเอกสาร JSON ด้วยค่าต่อไปนี้:

  • Error ID: รหัสเฉพาะของข้อผิดพลาด
  • ข้อความแสดงข้อผิดพลาด: ข้อความแสดงข้อผิดพลาดเฉพาะที่สามารถช่วยคุณระบุสาเหตุของข้อผิดพลาดการรับรองความถูกต้อง
  • รหัสความสัมพันธ์: GUID ที่ใช้สำหรับวัตถุประสงค์ในการดีบัก ถ้าคุณเปิดใช้งานการบันทึกการวินิจฉัย รหัสความสัมพันธ์จะแสดงอยู่ในล็อกข้อผิดพลาดของเซิร์ฟเวอร์
  • การประทับเวลา: วันที่และเวลาที่ข้อผิดพลาดถูกสร้างขึ้น

ข้อความแสดงข้อผิดพลาดจะแสดงในภาษาเริ่มต้นของผู้ใช้ที่ลงชื่อเข้าใช้ ถ้าผู้ใช้ไม่ได้ลงชื่อเข้าใช้ หน้าการลงชื่อเข้าใช้จะแสดงสำหรับผู้ใช้เพื่อให้ลงชื่อเข้าใช้ ตัวอย่างเช่น การตอบสนองที่เป็นข้อผิดพลาดมีลักษณะดังนี้:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

รายละเอียดจุดสิ้นสุดโทเค็น

นอกจากนี้คุณยังสามารถรับโทเค็นโดยการร้องขอไปยังจุดสิ้นสุด /token ซึ่งแตกต่างจากจุดสิ้นสุดของการอนุญาตในลักษณะที่จุดสิ้นสุดของการอนุญาตรับตรรกะโทเค็นในหน้าที่แยกต่างหาก (redirect_uri) ในขณะที่จุดสิ้นสุดของโทเค็นรับตรรกะโทเค็นในหน้าเดียวกัน URL สำหรับจุดสิ้นสุดของโทเค็นคือ: <portal_url>/_services/auth/token จุดสิ้นสุดของโทเค็นสนับสนุนพารามิเตอร์ต่อไปนี้:

พารามิเตอร์ จำเป็นหรือไม่ คำอธิบาย
client_id ไม่ สตริงที่ถูกส่งผ่านเมื่อทำการเรียกไปยังจุดสิ้นสุดที่อนุญาต คุณต้องให้แน่ใจว่ารหัสไคลเอนต์ได้รับการ ลงทะเบียนกับพอร์ทัลแล้ว มิฉะนั้น ข้อผิดพลาดจะแสดงขึ้น รหัสไคลเอนต์จะถูกเพิ่มในการอ้างสิทธิ์ในโทเค็นเป็นพารามิเตอร์ aud และ appid และไคลเอนต์สามารถใช้เพื่อตรวจสอบว่าโทเค็นที่ส่งคืนนั้นสำหรับแอปของรายการเหล่านั้นหรือไม่
ความยาวสูงสุด 36 อักขระ รองรับเฉพาะอักขระตัวอักษรผสมตัวเลขและยัติภังค์
redirect_uri ไม่ URL ของพอร์ทัลที่สามารถส่งและรับการตอบสนองต่อการรับรองความถูกต้อง คุณจะต้องลงทะเบียนสำหรับ client_id เฉพาะที่ใช้ในการโทร และควรมีค่าที่เหมือนกันทุกประการกับที่ลงทะเบียนไว้
สถานะ ไม่ ค่าที่รวมอยู่ในการร้องขอที่ส่งคืนในการตอบสนองโทเค็น ซึ่งสามารถเป็นสตริงของเนื้อหาใด ๆ ที่คุณต้องการใช้ โดยปกติ ค่าที่ไม่ซ้ำกันที่สร้างขึ้นแบบสุ่มจะถูกใช้เพื่อป้องกันการโจมตีปลอมของการร้องขอข้ามไซต์
ความยาวสูงสุด 20 อักขระ
nonce ไม่ ค่าสตริงที่ถูกส่งโดยไคลเอนต์ที่อยู่ในโทเค็นรหัสที่เป็นผลลัพธ์เป็นการอ้างสิทธิ์ จากนั้นไคลเอนต์สามารถตรวจสอบค่านี้เพื่อลดปัญหาการโจมตีการเล่นโทเค็นซ้ำ ความยาวสูงสุด 20 อักขระ
response_type ไม่ พารามิเตอร์นี้สนับสนุนเฉพาะ token เป็นค่า ซึ่งช่วยให้แอปของคุณสามารถรับโทเค็นการเข้าถึงจากจุดสิ้นสุดที่อนุญาตทันทีโดยไม่ต้องทำการร้องขอครั้งที่สองไปยังจุดสิ้นสุดที่อนุญาต

หมายเหตุ

แม้ว่าพารามิเตอร์ client_id, redirect_uri, state และ nonce จะไม่จำเป็น แต่เราขอแนะนำให้ใช้เพื่อให้แน่ใจว่าการรวมของคุณมีความปลอดภัย

การตอบสนองที่เสร็จเรียบร้อยแล้ว

จุดสิ้นสุดโทเค็นส่งคืนสถานะและ expires_in เป็นส่วนหัวของการตอบรับ และโทเค็นในเนื้อความของฟอร์ม

การตอบสนองข้อผิดพลาด

ข้อผิดพลาดในจุดสิ้นสุดโทเค็นจะส่งคืนเป็นเอกสาร JSON ด้วยค่าต่อไปนี้:

  • Error ID: รหัสเฉพาะของข้อผิดพลาด
  • ข้อความแสดงข้อผิดพลาด: ข้อความแสดงข้อผิดพลาดเฉพาะที่สามารถช่วยคุณระบุสาเหตุของข้อผิดพลาดการรับรองความถูกต้อง
  • รหัสความสัมพันธ์: GUID ที่ใช้สำหรับวัตถุประสงค์ในการดีบัก ถ้าคุณเปิดใช้งานการบันทึกการวินิจฉัย รหัสความสัมพันธ์จะแสดงอยู่ในล็อกข้อผิดพลาดของเซิร์ฟเวอร์
  • การประทับเวลา: วันที่และเวลาที่ข้อผิดพลาดถูกสร้างขึ้น

ข้อความแสดงข้อผิดพลาดจะแสดงในภาษาเริ่มต้นของผู้ใช้ที่ลงชื่อเข้าใช้ ถ้าผู้ใช้ไม่ได้ลงชื่อเข้าใช้ หน้าการลงชื่อเข้าใช้จะแสดงสำหรับผู้ใช้เพื่อให้ลงชื่อเข้าใช้ ตัวอย่างเช่น การตอบสนองที่เป็นข้อผิดพลาดมีลักษณะดังนี้:

{"ErrorId": "PortalSTS0001", "ErrorMessage": "Client Id provided in the request is not a valid client Id registered for this portal. Please check the parameter and try again.", "Timestamp": "4/5/2019 10:02:11 AM", "CorrelationId": "7464eb01-71ab-44bc-93a1-f221479be847" }

ตรวจสอบโทเค็นรหัส

เพียงแค่การรับโทเค็นรหัสไม่เพียงพอที่จะรับรองความถูกต้องของผู้ใช้ คุณยังต้องตรวจสอบลายเซ็นของโทเค็น และตรวจสอบว่าการอ้างสิทธิ์ในโทเค็นเป็นไปตามข้อกำหนดของแอปของคุณอีกด้วย จุดสิ้นสุดโทเค็นสาธารณะมีคีย์สาธารณะของพอร์ทัล ซึ่งสามารถใช้ในการตรวจสอบลายเซ็นของโทเค็นที่มีในพอร์ทัล URL สำหรับจุดสิ้นสุดโทเค็นสาธารณะคือ: <portal_url>/_services/auth/publickey

เปิดหรือปิดกโฟลว์การให้สิทธิ์โดยนัย

โดยค่าเริ่มต้น โฟลว์การให้สิทธิ์โดยนัยจะถูกเปิดใช้งาน ถ้าคุณต้องการปิดโฟลว์การให้สิทธิ์โดยนัย ให้ตั้งค่าของการตั้งค่าไซต์ Connector/ImplicitGrantFlowEnabled เป็น เท็จ

ถ้าการตั้งค่าไซต์นี้ไม่พร้อมใช้งานในพอร์ทัลของคุณ คุณจะต้อง สร้างการตั้งค่าไซต์ใหม่ ด้วยค่าที่เหมาะสม

กำหนดค่าการมีผลบังคับใช้โทเค็น

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

ตัวอย่างเช่น เมื่อต้องการตั้งค่าการมีผลบังคับใช้โทเคนเป็น 30 นาที ให้ตั้งค่าของการตั้งค่าไซต์ ImplicitGrantFlow/TokenExpirationTime เป็น 1800 เมื่อต้องการตั้งค่าการมีผลบังคับใช้โทเคนเป็น 1 ชั่วโมง ให้ตั้งค่าของการตั้งค่าไซต์ ImplicitGrantFlow/TokenExpirationTime เป็น 3600

ลงทะเบียนรหัสไคลเอนต์สำหรับโฟลว์การให้สิทธิ์โดยนัย

คุณต้องลงทะเบียนรหัสไคลเอนต์ด้วยพอร์ทัลที่อนุญาตให้ใช้โฟลว์นี้ เมื่อต้องการลงทะเบียนรหัสไคลเอนต์ คุณต้องสร้างการตั้งค่าไซต์ต่อไปนี้:

การตั้งค่าไซต์ Value
ImplicitGrantFlow/RegisteredClientId ค่ารหัสไคลเอนต์ที่ถูกต้องที่ได้รับอนุญาตสำหรับพอร์ทัลนี้ ค่าต้องคั่นด้วยเครื่องหมายอัฒภาค และสามารถประกอบด้วยอักขระพยัญชนะผสมตัวเลขและเครื่องหมายยัติภังค์ ความยาวสูงสุด 36 อักขระ
ImplicitGrantFlow/{ClientId}/RedirectUri URI เปลี่ยนเส้นทางที่ถูกต้องที่ได้รับอนุญาตสำหรับรหัสไคลเอ็นต์เฉพาะ ค่าต้องคั่นด้วยเครื่องหมายอัฒภาค URL ที่ป้อนต้องเป็นของเว็บเพจของพอร์ทัลที่ใช้ได้

โค้ดตัวอย่าง

คุณสามารถใช้โค้ดตัวอย่างต่อไปนี้เพื่อเริ่มต้น โดยการใช้การให้สิทธิ์โดยนัย OAuth 2.0 กับ API ของพอร์ทัล Power Apps

ใช้โทเค็น Portal OAuth กับ Web API ภายนอก

ตัวอย่างนี้คือโครงการที่ใช้ ASP.NET และใช้ในการตรวจสอบโทเค็น ID ที่ออกโดยพอร์ทัล Power Apps สามารถพบตัวอย่างที่สมบูรณ์ได้ที่นี่: ใช้โทเค็น Portal OAuth กับ Web API ภายนอก

อนุญาตตัวอย่างจุดสิ้นสุด

ตัวอย่างนี้แสดงวิธีการอนุญาตให้จุดสิ้นสุดส่งคืนโทเค็น ID เป็นส่วนใน URL ที่เปลี่ยนเส้นทาง นอกจากนี้ ยังครอบคลุมถึงการตรวจสอบความถูกต้องของสถานะที่สนับสนุนในการให้สิทธิ์โดยนัย สามารถพบตัวอย่างได้ที่นี่: อนุญาตตัวอย่างจุดสิ้นสุด

ตัวอย่างจุดสิ้นสุดโทเค็น

ตัวอย่างนี้แสดงวิธีที่คุณสามารถใช้ฟังก์ชัน getAuthenticationToken เพื่อดึงข้อมูลโทเค็น ID โดยใช้จุดสิ้นสุดโทเค็นในพอร์ทัล Power Apps สามารถพบตัวอย่างได้ที่นี่: ตัวอย่างจุดสิ้นสุดโทเค็น