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

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

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

ภาพรวม

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

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

รูปต่อไปนี้ให้ข้อมูลในระดับสูง

รูปที่ 1 ภาพนามธรรมของขั้นตอน OAuth

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

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

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

โทเค็นเพื่อการเข้าถึงอาจมีรูปแบบ โครงสร้าง และวิธีการใช้แตกต่างกัน (เช่น พร็อพเพอร์ตี้การเข้ารหัสลับ) ตามข้อกําหนดด้านความปลอดภัยของผู้ให้บริการ GTAF รองรับเฉพาะโทเค็นเพื่อการเข้าถึงของประเภทผู้ถือซึ่งกําหนดไว้ใน [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 ปลายทางต้องไม่มีคอมโพเนนต์ Fragment
• เนื่องจากคําขอที่ส่งไปยังปลายทางโทเค็นทําให้เกิดการส่งข้อมูลรับรองที่เป็นข้อความที่ชัดเจน (ในคําขอและการตอบกลับ HTTP) เซิร์ฟเวอร์ OAuth ของผู้ให้บริการจึงต้องใช้ TLS ในการส่งคําขอไปยังปลายทางของโทเค็น
• GTAF จะใช้เมธอด HTTP "POST" เมื่อขอโทเค็นเพื่อการเข้าถึง
• พารามิเตอร์ที่ส่งโดยไม่มีค่าจะต้องถือว่าละเว้นจากคําขอ เซิร์ฟเวอร์ OAuth ต้องไม่สนใจพารามิเตอร์คําขอที่ไม่รู้จัก ต้องมีพารามิเตอร์คําขอและการตอบกลับไม่เกิน 1 ครั้ง
• GTAF รองรับเฉพาะโทเค็นเพื่อการเข้าถึงประเภทผู้ถือ

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

ปลายทางการให้สิทธิ์และโทเค็นจะอนุญาตให้ไคลเอ็นต์ระบุขอบเขตของคําขอเข้าถึงโดยใช้พารามิเตอร์คําขอ "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 (OK) \

• access_token: ต้องระบุ โทเค็นการเข้าถึงที่ออกโดยเซิร์ฟเวอร์ OAuth GTAF คาดหวังให้ปลายทางของโทเค็นแสดงผลโทเค็นสําหรับผู้ถือ
• expires_in: REQUIRED อายุการใช้งานของโทเค็นเพื่อการเข้าถึงเป็นวินาที ตัวอย่างเช่น ค่า "3600" แสดงว่าโทเค็นเพื่อการเข้าถึงจะหมดอายุภายใน 1 ชั่วโมงหลังจากสร้างการตอบกลับ หากไม่ระบุ เซิร์ฟเวอร์ OAuth ควรระบุเวลาหมดอายุด้วยวิธีอื่นหรือบันทึกค่าเริ่มต้น
• token_type: REQUIRED ประเภทของโทเค็นที่ออก ดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นประเภทต่างๆ ได้ที่ส่วน 7.1 ของ RFC 6749 ค่านี้ไม่คํานึงถึงตัวพิมพ์เล็กหรือใหญ่ GTAF รองรับเฉพาะโทเค็นของผู้ถือเมื่อเขียนรายการนี้
• Refresh_token: ไม่บังคับ โทเค็นการรีเฟรชซึ่งใช้เพื่อขอโทเค็นเพื่อการเข้าถึงใหม่ได้โดยใช้การให้สิทธิ์เดียวกัน
• ขอบเขต: (ไม่บังคับ) หากนําไปใช้และเหมือนกับขอบเขตที่ 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 คําขอทั้งหมดจะส่งผ่าน TLS (เช่น HTTPS) และ GTAF ผสานรวมกับเซิร์ฟเวอร์ OAuth โดยไม่มีใบรับรอง TLS ที่ถูกต้องไม่ได้ GTAF สามารถส่งผ่านโทเค็นโทเค็นที่กําหนดค่าได้ และจะส่งขอบเขตที่ว่างเปล่าหากไม่ได้กําหนดค่า

GTAF คาดว่าจะส่งคืนโทเค็นเพื่อการเข้าถึงพร้อมกับค่า "expires_in" ค่า (Time to Live) ค่าexpir_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	คําขอไม่ถูกต้อง	คําขอไม่มีพารามิเตอร์ที่จําเป็น ประกอบด้วยค่าพารามิเตอร์ที่ไม่รองรับ (นอกเหนือจากประเภทการให้สิทธิ์) พารามิเตอร์ซ้ํา มีข้อมูลเข้าสู่ระบบหลายรายการ กลไกมากกว่า 1 อย่างสําหรับการตรวจสอบสิทธิ์กับ GTAF หรือรูปแบบอื่นๆ
HTTP 401	ลูกค้าไม่ถูกต้อง	การตรวจสอบสิทธิ์ไคลเอ็นต์ล้มเหลว (เช่น ไคลเอ็นต์ที่ไม่รู้จัก ไม่รวมการตรวจสอบสิทธิ์ไคลเอ็นต์ หรือวิธีการตรวจสอบสิทธิ์ที่ไม่รองรับ) เซิร์ฟเวอร์ OAuth อาจส่งคืนรหัสสถานะ HTTP 401 (ไม่ได้รับอนุญาต) เพื่อระบุรูปแบบการตรวจสอบสิทธิ์ HTTP หากไคลเอ็นต์พยายามตรวจสอบสิทธิ์ผ่านช่องส่วนหัวของ "Authorization" ส่วนหัวของคําขอ เซิร์ฟเวอร์ OAuth ต้องตอบกลับด้วยรหัสสถานะ HTTP 401 (ไม่ได้รับอนุญาต) และรวมช่องส่วนหัวการตอบกลับ "WWW-Authentication" ที่ตรงกับรูปแบบการตรวจสอบสิทธิ์ที่ไคลเอ็นต์ใช้
HTTP 500	เซิร์ฟเวอร์ OAuth ทํางานล้มเหลว

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