OAuth สําหรับ Data Plan Agent API

เอกสารที่เกี่ยวข้อง

OAuth 2.0 ได้รับการกำหนดมาตรฐานเป็น RFC 6749 ดูเอกสารโดยละเอียดได้ที่ https://oauth.net/2 การตรวจสอบสิทธิ์พื้นฐาน HTTP มีการกำหนดไว้ใน ส่วนที่ 2 ของ RFC 2617

ภาพรวม

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

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

รูปภาพต่อไปนี้แสดงโฟลว์ของข้อมูลในภาพรวม

รูปที่ 1 ขั้นตอน OAuth โดยย่อ

โทเค็นเพื่อการเข้าถึง

โทเค็นการเข้าถึงคือข้อมูลเข้าสู่ระบบที่ GTAF ใช้เพื่อเข้าถึงรายละเอียดแพ็กเกจอินเทอร์เน็ต จาก DPA ของผู้ให้บริการ โทเค็นเพื่อการเข้าถึงคือสตริงที่แสดง การให้สิทธิ์ที่ออกให้กับ GTAF โดยปกติแล้ว สตริงจะทึบแสงสำหรับ GTAF โทเค็นแสดงถึงขอบเขตและระยะเวลาการเข้าถึงที่เฉพาะเจาะจง ซึ่งผู้ใช้ปลายทางให้แก่ผู้ให้บริการ และ DPA รวมถึงเซิร์ฟเวอร์ OAuth ของผู้ให้บริการบังคับใช้

โทเค็นเพื่อการเข้าถึงจะให้เลเยอร์การแยกข้อมูล โดยแทนที่โครงสร้างการให้สิทธิ์ต่างๆ (เช่น ชื่อผู้ใช้และรหัสผ่าน) ด้วยโทเค็นเดียวที่ DPA เข้าใจ การแยกส่วนนี้ช่วยให้สามารถออกโทเค็นเพื่อการเข้าถึงที่เข้มงวดกว่าการให้สิทธิ์ที่ใช้ในการขอโทเค็น รวมถึงไม่จำเป็นที่ DPA จะต้องทำความเข้าใจวิธีการตรวจสอบสิทธิ์ที่หลากหลาย

โทเค็นเพื่อการเข้าถึงอาจมีรูปแบบ โครงสร้าง และวิธีการใช้งานที่แตกต่างกัน (เช่น คุณสมบัติการเข้ารหัส) โดยขึ้นอยู่กับข้อกำหนดด้านความปลอดภัยของผู้ให้บริการ GTAF รองรับเฉพาะโทเค็นเพื่อการเข้าถึงประเภท Bearer ที่กําหนดไว้ใน [RFC6750]

การตรวจสอบสิทธิ์ไคลเอ็นต์

GTAF ทำหน้าที่เป็น "ไคลเอ็นต์ที่เป็นความลับ" และสามารถเก็บรักษารหัสผ่านให้ปลอดภัยได้ ปัจจุบัน GTAF รองรับเฉพาะการตรวจสอบสิทธิ์ HTTP ขั้นพื้นฐานเพื่อตรวจสอบสิทธิ์ กับ DPA ระบบจะเข้ารหัสตัวระบุไคลเอ็นต์โดยใช้อัลกอริทึมการเข้ารหัส "application/x-www-form-urlencoded" และใช้ค่าที่เข้ารหัสเป็นชื่อผู้ใช้ ส่วนรหัสผ่านจะเข้ารหัสโดยใช้อัลกอริทึมเดียวกันและใช้เป็นรหัสผ่าน

ไคลเอ็นต์แบบลับ เช่น GTAF ซึ่งออกข้อมูลเข้าสู่ระบบไคลเอ็นต์ จะตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ OAuth ของผู้ให้บริการขณะส่งคำขอไปยังโทเค็น ปลายทาง การตรวจสอบสิทธิ์ไคลเอ็นต์ใช้สำหรับ \

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

GTAF ใช้พารามิเตอร์คำขอ "client_id" เพื่อระบุตัวตนเมื่อส่งคำขอไปยังปลายทางโทเค็น

ความสามารถในการหมุนเวียนข้อมูลเข้าสู่ระบบของไคลเอ็นต์มีความสำคัญเป็นพิเศษ เซิร์ฟเวอร์ OAuth ต้องรองรับข้อมูลเข้าสู่ระบบ 2 คู่พร้อมกันในระหว่างการหมุนเวียน และต้องมีความสามารถในการปิดใช้ข้อมูลเข้าสู่ระบบ ในการหมุนเวียนข้อมูลเข้าสู่ระบบตามปกติ ให้ทำดังนี้

1. ผู้ให้บริการสร้างข้อมูลเข้าสู่ระบบใหม่ในเซิร์ฟเวอร์ OAuth และส่งข้อมูลเข้าสู่ระบบให้ผู้จัดการฝ่ายดูแลลูกค้าด้านเทคนิคอย่างปลอดภัย
2. Google จะทดสอบข้อมูลเข้าสู่ระบบใหม่และเปลี่ยนการกำหนดค่า GTAF ให้ใช้ ข้อมูลเข้าสู่ระบบใหม่
3. Google จะแจ้งให้ผู้ให้บริการทราบว่าอาจมีการปิดใช้ข้อมูลเข้าสู่ระบบเก่า
4. ผู้ให้บริการปิดใช้ข้อมูลเข้าสู่ระบบและแจ้งให้ Google ทราบ
5. Google จะยืนยันว่าข้อมูลเข้าสู่ระบบเก่าใช้งานไม่ได้อีกต่อไป

เซิร์ฟเวอร์ OAuth ต้องรองรับกระบวนการหมุนเวียนข้างต้นได้

ปลายทางของโทเค็น

GTAF ใช้ปลายทางโทเค็นเพื่อรับโทเค็นเพื่อการเข้าถึงโดยการแสดง การให้สิทธิ์หรือโทเค็นการรีเฟรช ระบบจะใช้ปลายทางโทเค็นกับการให้สิทธิ์ทุกครั้ง ยกเว้นประเภทการให้สิทธิ์โดยนัย (เนื่องจากมีการออกโทเค็นเพื่อการเข้าถึง โดยตรง)

ต่อไปนี้คือประเด็นบางส่วนที่ควรพิจารณาขณะกำหนดค่าปลายทางโทเค็น

• ควรระบุตำแหน่งของปลายทางโทเค็นในเอกสารประกอบของบริการ
• URI ของปลายทางอาจมีคอมโพเนนต์การค้นหาที่จัดรูปแบบ "application/x-www-form-urlencoded" ซึ่งต้องเก็บไว้เมื่อเพิ่มพารามิเตอร์การค้นหาเพิ่มเติม URI ของปลายทางต้องไม่มีคอมโพเนนต์ของตัวแปร
• เนื่องจากคำขอไปยังปลายทางโทเค็นส่งผลให้มีการส่งข้อมูลเข้าสู่ระบบแบบข้อความธรรมดา (ในคำขอและการตอบกลับ HTTP) เซิร์ฟเวอร์ OAuth ของผู้ให้บริการจึงต้องใช้ TLS เพื่อส่งคำขอไปยังปลายทางโทเค็น
• GTAF ใช้เมธอด "POST" ของ HTTP เมื่อส่งคำขอโทเค็นการเข้าถึง
• พารามิเตอร์ที่ส่งโดยไม่มีค่าต้องถือว่าไม่ได้รวมอยู่ในคำขอ เซิร์ฟเวอร์ OAuth ต้องไม่สนใจพารามิเตอร์คำขอที่ไม่รู้จัก ต้องไม่รวมพารามิเตอร์คำขอและคำตอบมากกว่า 1 ครั้ง
• GTAF รองรับเฉพาะโทเค็นเพื่อการเข้าถึงประเภท Bearer

ขอบเขตโทเค็นเพื่อการเข้าถึง

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

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF ไม่ได้กำหนดให้ใช้ขอบเขต แต่รองรับฟีเจอร์นี้ ดูข้อมูลเพิ่มเติมได้ที่ส่วนที่ 3.3 ของ RFC 6749

การออกโทเค็นเพื่อการเข้าถึง

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

การตอบกลับที่สำเร็จ

เมื่อ GTAF ส่งคำขอ เซิร์ฟเวอร์ OAuth จะออกโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช (ไม่บังคับ) และสร้างการตอบกลับโดยการเพิ่มพารามิเตอร์ต่อไปนี้ลงในเนื้อหาของเอนทิตีในการตอบกลับ HTTP ที่มีรหัสสถานะ 200 (ตกลง) \

• access_token: ต้องระบุ โทเค็นเพื่อการเข้าถึงที่เซิร์ฟเวอร์ OAuth ออกให้ GTAF คาดหวังว่าปลายทางโทเค็นจะส่งคืนโทเค็นผู้ถือ
• expires_in: ต้องระบุ อายุการใช้งานของโทเค็นเพื่อการเข้าถึงเป็นวินาที ตัวอย่างเช่น ค่า "3600" หมายความว่าโทเค็นเพื่อการเข้าถึงจะหมดอายุใน 1 ชั่วโมงนับจากเวลาที่สร้างการตอบกลับ หากไม่มีการระบุ เซิร์ฟเวอร์ OAuth ควรระบุเวลาหมดอายุด้วยวิธีอื่นหรือบันทึกค่าเริ่มต้น
• token_type: ต้องระบุ ประเภทของโทเค็นที่ออก ดูข้อมูลเพิ่มเติม เกี่ยวกับโทเค็นประเภทต่างๆ ได้ที่ ส่วน 7.1 ของ RFC 6749 ค่านี้จะไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ขณะนี้ GTAF รองรับเฉพาะโทเค็นผู้ถือ
• refresh_token: ไม่บังคับ โทเค็นการรีเฟรชซึ่งใช้เพื่อรับโทเค็นเพื่อการเข้าถึงใหม่ได้โดยใช้การให้สิทธิ์เดียวกัน
• scope: ไม่บังคับ หากมีการติดตั้งใช้งานและเหมือนกับขอบเขตที่ GTAF ร้องขอ มิฉะนั้นจะต้องระบุ

พารามิเตอร์จะรวมอยู่ในเอนทิตี-บอดี้ของการตอบกลับ HTTP โดยใช้ "application/json" ระบบจะแปลงพารามิเตอร์เป็นโครงสร้าง JavaScript Object Notation (JSON) โดยการเพิ่มพารามิเตอร์แต่ละรายการที่ระดับโครงสร้างสูงสุด ชื่อพารามิเตอร์และค่าสตริงจะรวมเป็นสตริง JSON ค่าตัวเลข จะรวมอยู่ในรูปแบบตัวเลข JSON ลำดับของพารามิเตอร์ไม่สำคัญและ อาจแตกต่างกัน

เซิร์ฟเวอร์การให้สิทธิ์ต้องรวมฟิลด์ส่วนหัวการตอบกลับ HTTP "Cache-Control" ที่มีค่าเป็น "no-store" ไว้ในการตอบกลับที่มีโทเค็น ข้อมูลเข้าสู่ระบบ หรือข้อมูลที่ละเอียดอ่อนอื่นๆ รวมถึงฟิลด์ส่วนหัวการตอบกลับ "Pragma" ที่มีค่าเป็น "no-cache"

ตัวอย่างเช่น

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

ต่อไปนี้คือประเด็นสำคัญบางประการที่ควรพิจารณา

• GTAF จะไม่สนใจชื่อค่าที่ไม่รู้จักในคำตอบ
• ขนาดของโทเค็นและค่าอื่นๆ ที่ได้รับจากเซิร์ฟเวอร์ OAuth จะไม่ กำหนด
• GTAF ควรหลีกเลี่ยงการคาดเดาเกี่ยวกับขนาดค่า เซิร์ฟเวอร์ OAuth ควรกำหนดขนาดของค่าที่ออก

การตอบกลับข้อผิดพลาด

หากคำขอการให้สิทธิ์ล้มเหลวเนื่องจากสาเหตุใดก็ตาม เช่น ไม่มี ไม่ถูกต้อง หรือ URI การเปลี่ยนเส้นทางไม่ตรงกัน หรือหากไม่มีตัวระบุไคลเอ็นต์ หรือไม่ถูกต้อง เซิร์ฟเวอร์ OAuth ควรตอบกลับด้วยรหัสสถานะ HTTP 400 (คำขอไม่ถูกต้อง) (เว้นแต่จะระบุไว้เป็นอย่างอื่น) และควรรวมพารามิเตอร์อย่างน้อย 1 รายการที่ระบุไว้ในส่วนการตอบกลับและรหัสข้อผิดพลาด

การให้สิทธิ์ใน GTAF

การให้สิทธิ์คือข้อมูลเข้าสู่ระบบที่แสดงถึงการให้สิทธิ์ของผู้ใช้ปลายทาง (ในการเข้าถึงทรัพยากรที่ได้รับการปกป้อง เช่น ข้อมูลยอดคงเหลือ) ซึ่ง GTAF ใช้เพื่อรับโทเค็นเพื่อการเข้าถึง

GTAF ใช้ประเภทการให้สิทธิ์ client_credentials ในประเภทการให้สิทธิ์ client_credentials GTAF จะขอโทเค็นโดยใช้คำขอ HTTP POST และ HTTP Basic Authentication ระบบจะส่งคำขอทั้งหมดผ่าน TLS (เช่น HTTPS) และ GTAF จะผสานรวมกับเซิร์ฟเวอร์ OAuth ไม่ได้หากไม่มีใบรับรอง TLS ที่ถูกต้อง GTAF สามารถส่งขอบเขตโทเค็นที่กำหนดค่าได้ และจะส่งขอบเขตว่างหากไม่ได้กำหนดค่าไว้

GTAF คาดหวังว่าจะได้รับโทเค็นเพื่อการเข้าถึงพร้อมกับค่า "expires_in" (เวลาที่จะใช้งานได้) ค่า expires_in ควรมีค่าอย่างน้อย 900 วินาที และไม่ควรเกิน 2-3 ชั่วโมง การขอโทเค็นใหม่ต้องไม่ทำให้โทเค็นที่มีอยู่หมดอายุก่อนเวลา

ดูรายละเอียดเพิ่มเติมเกี่ยวกับประเภทการให้สิทธิ์ต่างๆ ได้ที่ส่วน 1.3 ของ RFC 6749

ตัวอย่างคำขอและการตอบกลับ

สมมติว่า GTAF มีการกำหนดค่าต่อไปนี้สำหรับเซิร์ฟเวอร์ OAuth

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

หมายเหตุ: รหัสลับไคลเอ็นต์สำหรับ DPA จริงต้องปลอดภัยกว่ารหัสที่ แสดงในตัวอย่างมาก

หากต้องการสร้างสตริงการให้สิทธิ์ ระบบจะต่อรหัสไคลเอ็นต์ ":" และรหัสผ่าน เข้าด้วยกันและเข้ารหัส Base64 ซึ่งสามารถจำลองได้ในอินเทอร์เฟซบรรทัดคำสั่ง ดังนี้

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

จากนั้น GTAF จะส่งคำขอ HTTPS POST ไปยังเซิร์ฟเวอร์ OAuth โดยใช้ข้อมูลเข้าสู่ระบบเหล่านี้ ประเภทการให้สิทธิ์ client_credentials และขอบเขตที่กำหนดค่าไว้ สำหรับ ตัวอย่าง คำขอของ GTAF จะมีลักษณะคล้ายกับคำขอที่สร้างโดย

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

ส่วนหัวที่ GTAF ใช้จะไม่ตรงกับส่วนหัวที่ curl ส่ง แม้ว่าส่วนหัวการให้สิทธิ์จะเหมือนกันก็ตาม

GTAF คาดหวังการตอบกลับในรูปแบบต่อไปนี้

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

ตัวอย่างการตอบกลับที่ถูกต้องมีดังนี้

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

หมายเหตุ: การตอบกลับต้องเป็น JSON ที่ถูกต้อง

การตอบกลับและรหัสข้อผิดพลาด

หากคำขอการให้สิทธิ์จาก GTAF ล้มเหลวเนื่องจากเหตุผลใดก็ตามที่ระบุไว้ใน ส่วนการตอบกลับข้อผิดพลาด เซิร์ฟเวอร์ OAuth ต้องตอบกลับด้วยรหัสสถานะ HTTP 400 (คำขอไม่ถูกต้อง) (เว้นแต่จะระบุไว้เป็นอย่างอื่น) และรวมพารามิเตอร์ต่อไปนี้อย่างใดอย่างหนึ่งไว้ในการตอบกลับ

เช่น \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF คาดหวังให้เซิร์ฟเวอร์ OAuth รองรับการตอบกลับข้อผิดพลาดต่อไปนี้

รหัสข้อผิดพลาด	การตอบกลับ	เหตุผล
HTTP 400	invalid_request	คำขอไม่มีพารามิเตอร์ที่จำเป็น มีค่าพารามิเตอร์ที่ไม่รองรับ (นอกเหนือจากประเภทการให้สิทธิ์) มีพารามิเตอร์ซ้ำ มีข้อมูลเข้าสู่ระบบหลายรายการ ใช้กลไกมากกว่า 1 อย่างในการตรวจสอบสิทธิ์กับ GTAF หรือมีรูปแบบไม่ถูกต้อง
HTTP 401	invalid_client	การตรวจสอบสิทธิ์ไคลเอ็นต์ล้มเหลว (เช่น ไคลเอ็นต์ที่ไม่รู้จัก ไม่มีการตรวจสอบสิทธิ์ไคลเอ็นต์ หรือใช้วิธีการตรวจสอบสิทธิ์ที่ไม่รองรับ) เซิร์ฟเวอร์ OAuth อาจแสดงรหัสสถานะ HTTP 401 (ไม่ได้รับอนุญาต) เพื่อระบุว่ารองรับรูปแบบการตรวจสอบสิทธิ์ HTTP ใดบ้าง หากไคลเอ็นต์พยายามตรวจสอบสิทธิ์ผ่านฟิลด์ส่วนหัวคำขอ "Authorization" เซิร์ฟเวอร์ OAuth จะต้องตอบกลับด้วยรหัสสถานะ HTTP 401 (ไม่ได้รับอนุญาต) และใส่ฟิลด์ส่วนหัวการตอบกลับ "WWW-Authenticate" ที่ตรงกับรูปแบบการตรวจสอบสิทธิ์ที่ไคลเอ็นต์ใช้
HTTP 500	เซิร์ฟเวอร์ OAuth ล้มเหลว

ดูรายละเอียดของการตอบกลับอื่นๆ ที่ใช้ในการแก้ไขข้อบกพร่องได้ที่ ส่วนที่ 5.2 ของ RFC 6749