OAuth 2.0 สำหรับแอปบนเดสก์ท็อป

เอกสารนี้อธิบายวิธีที่แอปพลิเคชันบนเดสก์ท็อป (เช่น แอปพลิเคชันที่ทำงานบน Windows, macOS หรือ Linux หรือเครื่องมืออินเทอร์เฟซบรรทัดคำสั่ง (CLI)) ใช้ปลายทาง OAuth 2.0 ของ Google เพื่อให้สิทธิ์เข้าถึง Google API

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

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

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

ไลบรารีและตัวอย่าง

เราขอแนะนำให้ใช้ไลบรารีของไคลเอ็นต์ Google API สำหรับภาษาโปรแกรมของคุณ (เช่น Python, Java, Node.js, Go, .NET) เมื่อใช้ OAuth 2.0 สำหรับแอปพลิเคชันบนเดสก์ท็อป ไลบรารีของไคลเอ็นต์จะจัดการการให้สิทธิ์ผู้ใช้และการจัดการโทเค็น ซึ่งทำให้การติดตั้งใช้งานง่ายขึ้นและมีข้อผิดพลาดน้อยกว่าการใช้ปลายทาง HTTP/REST ระดับต่ำกว่าโดยตรง

สำหรับแอปบนอุปกรณ์เคลื่อนที่ โปรดดูคู่มือการให้สิทธิ์ของ Android และ iOS

สำหรับแอปที่ทำงานบนอุปกรณ์ที่ไม่รองรับเบราว์เซอร์ของระบบหรือมีความสามารถในการป้อนข้อมูลที่จำกัด เช่น ทีวี คอนโซลเกม กล้อง หรือเครื่องพิมพ์ โปรดดู OAuth 2.0 สำหรับทีวีและอุปกรณ์ หรือการลงชื่อเข้าใช้ในทีวีและอุปกรณ์ที่มีการป้อนข้อมูลที่จำกัด

ข้อกำหนดเบื้องต้น

เปิดใช้ API สำหรับโปรเจ็กต์

แอปพลิเคชันที่เรียกใช้ Google API จะต้องเปิดใช้ API เหล่านั้นในคอนโซล API

วิธีเปิดใช้ API สำหรับโปรเจ็กต์

1. เปิดคลัง API ในคอนโซล Google API
2. หากได้รับข้อความแจ้ง ให้เลือกโปรเจ็กต์หรือสร้างโปรเจ็กต์ใหม่
3. ไลบรารี API จะแสดง API ทั้งหมดที่มีอยู่ โดยจัดกลุ่มตามตระกูลผลิตภัณฑ์และความนิยม หาก API ที่ต้องการเปิดใช้ไม่ปรากฏในรายการ ให้ใช้การค้นหาเพื่อค้นหา API หรือคลิกดูทั้งหมดในกลุ่มผลิตภัณฑ์ที่ API นั้นอยู่
4. เลือก API ที่ต้องการเปิดใช้ แล้วคลิกปุ่มเปิดใช้
5. เปิดใช้การเรียกเก็บเงินเมื่อได้รับข้อความแจ้ง
6. หากได้รับข้อความแจ้ง ให้อ่านและยอมรับข้อกำหนดในการให้บริการของ API

สร้างข้อมูลเข้าสู่ระบบสำหรับการให้สิทธิ์

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

1. ไปที่หน้าลูกค้า
2. คลิกสร้างไคลเอ็นต์
3. เลือกประเภทแอปพลิเคชันเป็นแอปบนเดสก์ท็อป
4. ในช่องชื่อ ให้ป้อนชื่อสำหรับไคลเอ็นต์ OAuth ชื่อนี้จะแสดงในหน้าไคลเอ็นต์ของโปรเจ็กต์เพื่อระบุไคลเอ็นต์
5. คลิกสร้าง

ระบบจะสร้างรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์และแสดงในคอนโซล Google Cloud แอปบนเดสก์ท็อปเป็นไคลเอ็นต์สาธารณะและไม่สามารถเก็บข้อมูลลับไว้เป็นความลับได้ ใช้ PKCE (Proof Key for Code Exchange) เสมอเมื่อขอรหัสการให้สิทธิ์

ระบุขอบเขตการเข้าถึง

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

ก่อนเริ่มใช้การให้สิทธิ์ OAuth 2.0 เราขอแนะนำให้คุณระบุขอบเขตที่แอปจะต้องได้รับสิทธิ์เข้าถึง

เอกสารขอบเขต OAuth 2.0 API มีรายการขอบเขตทั้งหมดที่คุณอาจใช้เพื่อเข้าถึง Google APIs

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

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

ขั้นตอนที่ 1: สร้างตัวตรวจสอบและคำถามยืนยันรหัส

Google รองรับโปรโตคอล Proof Key for Code Exchange (PKCE) เพื่อทำให้ขั้นตอนของแอปที่ติดตั้งมีความปลอดภัยมากขึ้น ระบบจะสร้างตัวตรวจสอบรหัสที่ไม่ซ้ำกันสำหรับคำขอการให้สิทธิ์ทุกรายการ และจะส่งค่าที่แปลงแล้วซึ่งเรียกว่า "code_challenge" ไปยังเซิร์ฟเวอร์การให้สิทธิ์เพื่อรับรหัสการให้สิทธิ์

สร้างตัวตรวจสอบโค้ด

code_verifier คือสตริงแบบสุ่มที่เข้ารหัสด้วยเอนโทรปีสูงโดยใช้อักขระที่ไม่ได้สงวนไว้ [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" โดยมีความยาวขั้นต่ำ 43 อักขระและความยาวสูงสุด 128 อักขระ

ตัวตรวจสอบโค้ดควรมีเอนโทรปีมากพอที่จะทำให้คาดเดาค่าได้ยาก

สร้างรหัสยืนยัน

ระบบรองรับการสร้างการตรวจสอบโค้ด 2 วิธี

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

ขั้นตอนที่ 2: ส่งคำขอไปยังเซิร์ฟเวอร์ OAuth 2.0 ของ Google

หากต้องการขอสิทธิ์จากผู้ใช้ ให้ส่งคำขอไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google ที่ https://accounts.google.com/o/oauth2/v2/auth ปลายทางนี้จะจัดการการค้นหาเซสชันที่ใช้งานอยู่ ตรวจสอบสิทธิ์ผู้ใช้ และขอความยินยอมจากผู้ใช้ ปลายทางจะเข้าถึงได้ผ่าน SSL เท่านั้น และจะปฏิเสธการเชื่อมต่อ HTTP (ที่ไม่ใช่ SSL)

เซิร์ฟเวอร์การให้สิทธิ์รองรับพารามิเตอร์สตริงคำค้นหาต่อไปนี้สำหรับแอปพลิเคชันที่ติดตั้ง

ตัวอย่าง URL การให้สิทธิ์

แท็บด้านล่างแสดงตัวอย่าง URL การให้สิทธิ์สำหรับตัวเลือก URI การเปลี่ยนเส้นทางต่างๆ

URL ทั้ง 2 รายการเหมือนกันทุกประการ ยกเว้นค่าของพารามิเตอร์ redirect_uri นอกจากนี้ URL ยังมีพารามิเตอร์ response_type และ client_id ที่จำเป็น รวมถึงพารามิเตอร์ state ที่ไม่บังคับด้วย URL แต่ละรายการมีการขึ้นบรรทัดใหม่และเว้นวรรคเพื่อให้อ่านง่าย

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

ขั้นตอนที่ 3: Google แจ้งให้ผู้ใช้ให้ความยินยอม

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

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

ขั้นตอนที่ 4: จัดการการตอบกลับของเซิร์ฟเวอร์ OAuth 2.0

ลักษณะที่แอปพลิเคชันของคุณได้รับการตอบกลับการให้สิทธิ์จะขึ้นอยู่กับสคีม URI การเปลี่ยนเส้นทางที่ใช้ ไม่ว่าจะเป็นรูปแบบใด การตอบกลับจะมีรหัสการให้สิทธิ์ (code) หรือข้อผิดพลาด (error) เช่น error=access_denied บ่งชี้ว่าผู้ใช้ปฏิเสธคำขอ

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

ขั้นตอนที่ 5: แลกเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นการรีเฟรชและโทเค็นเพื่อการเข้าถึง

หากต้องการแลกรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึง ให้เรียกใช้ปลายทาง https://oauth2.googleapis.com/token และตั้งค่าพารามิเตอร์ต่อไปนี้

แม้ว่าการใช้ DPoP จะเป็นตัวเลือก แต่เราขอแนะนำให้ใช้เพื่อเพิ่มความปลอดภัย ความปลอดภัยของ DPoP ขึ้นอยู่กับการจำกัดคีย์ส่วนตัวไว้ในอุปกรณ์เดียว เราขอแนะนำให้จัดเก็บคีย์ในลักษณะที่ไม่สามารถคัดลอกออกจากอุปกรณ์ได้ เช่น โดยใช้ TPM, Secure Enclave หรือคีย์สโตร์อื่นๆ ที่สนับสนุนโดยฮาร์ดแวร์ หากต้องการใช้ DPoP แอปพลิเคชันของคุณต้องสร้าง JWT หลักฐาน DPoP ใหม่ที่ไม่ซ้ำกันสำหรับคำขอแต่ละรายการไปยังปลายทางโทเค็น และเพิ่มเป็นส่วนหัวของคำขอ HTTP

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอ

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

สร้างหลักฐาน DPoP

ขั้นตอนต่อไปนี้แสดงวิธีสร้างหลักฐาน DPoP โดยใช้ OpenSSL จากบรรทัดคำสั่ง

1. สร้างคู่คีย์ EC P-256

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. สร้างส่วนหัว DPoP

   ส่วนหัวต้องมีคำกล่าวอ้าง typ, alg และ jwk (คีย์สาธารณะ) ค่า x และ y คือพิกัดที่เข้ารหัส Base64Url ของคีย์สาธารณะ EC เข้ารหัส Base64Url สำหรับ JSON นี้

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. สร้างเพย์โหลด DPoP

   เพย์โหลดต้องมี jti (ตัวระบุที่ไม่ซ้ำกันสำหรับคำขอ), htm (เมธอด HTTP เช่น POST), htu (HTTP URI เช่น https://oauth2.googleapis.com/token) และ iat (เวลาที่ออก) หากคุณได้รับ Nonce จากเซิร์ฟเวอร์ในส่วนหัว DPoP-Nonce ในการตอบกลับคำขอก่อนหน้า คุณต้องใส่ค่า Nonce นั้นในการอ้างสิทธิ์ nonce การอ้างสิทธิ์ Nonce เป็นตัวเลือกสำหรับการแลกเปลี่ยนรหัสการให้สิทธิ์ และจะใช้เมื่อได้รับส่วนหัว DPoP-Nonce ก่อนหน้านี้เท่านั้น เข้ารหัส Base64Url สำหรับ JSON นี้

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   ค่า jti จะขึ้นอยู่กับประเภทของ Exchange ดังนี้

   • สำหรับการแลกเปลี่ยนรหัสการให้สิทธิ์ jti ต้องเป็นแฮช SHA256 ที่เข้ารหัส Base64Url ของรหัสการให้สิทธิ์: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))"
   • สำหรับการแลกเปลี่ยนโทเค็นการรีเฟรช jti ต้องเป็นตัวระบุที่ไม่ซ้ำกันต่อคำขอ: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER"
4. ลงนามในหลักฐาน:

   เชื่อมโยงส่วนหัวและเพย์โหลดที่เข้ารหัสด้วยจุด (.) จากนั้นลงนามผลลัพธ์ด้วยคีย์ส่วนตัวโดยใช้ ES256 โปรดทราบว่า JWS กำหนดให้ลายเซ็นต้องอยู่ในรูปแบบ R | S ที่เชื่อมโยงแบบข้อมูลดิบ (64 ไบต์สำหรับ P-256) หากใช้ OpenSSL โดยตรง คุณต้องแปลงลายเซ็นที่เข้ารหัส ASN.1 DER เริ่มต้นเป็นรูปแบบข้อมูลดิบนี้

การแลกเปลี่ยนที่สำเร็จจะแสดงด้วยการตอบกลับ 200 OK ที่มีโทเค็น หากใช้หลักฐาน DPoP ที่ถูกต้องในระหว่างการแลกเปลี่ยน โทเค็นการรีเฟรชที่ Google แสดงผลจะเชื่อมโยงกับคีย์ของคุณด้วย DPoP แต่โทเค็นเพื่อการเข้าถึงจะไม่เชื่อมโยงกับ DPoP โทเค็นเพื่อการเข้าถึงจะยังคงมี token_type ของ Bearer แทนที่จะเป็น DPoP นอกจากนี้ Google จะแสดงผลส่วนหัว HTTP DPoP-Nonce ในการตอบกลับด้วย ไคลเอ็นต์ต้องแคช Nonce นี้และรวมไว้ในการอ้างสิทธิ์ nonce ของหลักฐาน DPoP ในคำขอต่อๆ ไป (เช่น เมื่อแลกเปลี่ยนโทเค็นการรีเฟรชเป็นโทเค็นเพื่อการเข้าถึงใหม่ หรือเมื่อเรียกใช้ API ที่ได้รับการปกป้องด้วย DPoP) การใช้ Nonce ที่ออกก่อนเวลานี้จะช่วยหลีกเลี่ยงความล้มเหลวในการส่งไปกลับเพิ่มเติม (use_dpop_nonce) ในคำขอถัดไปได้

ต้องระบุหลักฐาน DPoP สำหรับคำขอแลกเปลี่ยนโทเค็นที่ส่งด้วยโทเค็นการรีเฟรชที่เชื่อมโยงกับ DPoP

การแลกเปลี่ยนที่ล้มเหลวจะเกิดขึ้นหากไม่มีส่วนหัว DPoP เมื่อคาดไว้ ไม่ถูกต้อง หรือหากหลักฐานใช้คีย์อื่นที่ไม่ใช่คีย์ที่เชื่อมโยงกับโทเค็น ในกรณีเหล่านี้ เซิร์ฟเวอร์จะแสดงข้อผิดพลาด 400 Bad Request หากหลักฐาน DPoP มีการอ้างสิทธิ์ htm หรือ htu ที่ไม่ตรงกัน, iat ที่หมดอายุ, jti ที่ใช้ซ้ำ หรือลายเซ็นที่ไม่ถูกต้อง Google จะแสดงรหัสข้อผิดพลาด invalid_dpop_proof หากจำเป็นต้องใช้ Nonce ของ DPoP เช่น ในระหว่างการแลกเปลี่ยนโทเค็นการรีเฟรช และการพิสูจน์ DPoP ไม่มีคำกล่าวอ้าง nonce หรือค่า Nonce ไม่เป็นที่ยอมรับสำหรับเซิร์ฟเวอร์ (เช่น หมดอายุ มีการใช้งานแล้ว หรือไม่ถูกต้อง) Google จะแสดงรหัสข้อผิดพลาด use_dpop_nonce พร้อมกับส่วนหัว HTTP DPoP-Nonce ที่มี Nonce ใหม่ซึ่งคุณสามารถใช้ในคำขอต่อๆ ไปได้ ข้อผิดพลาดอื่นๆ อาจแสดงผลเป็น invalid_grant

Google จะตอบกลับคำขอนี้โดยแสดงผลออบเจ็กต์ JSON ที่มีโทเค็นเพื่อการเข้าถึงที่มีอายุสั้นและโทเค็นการรีเฟรช

การตอบกลับจะมีฟิลด์ต่อไปนี้

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างส่วนหัวการตอบกลับและเนื้อหาที่สำเร็จเมื่อใช้ DPoP

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

ขั้นตอนที่ 6: ตรวจสอบขอบเขตที่ผู้ใช้ให้สิทธิ์

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

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

ดูข้อมูลโดยละเอียดเพิ่มเติมได้ที่วิธีจัดการสิทธิ์แบบละเอียด

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

เรียกใช้ Google API

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

คุณลองใช้ Google APIs ทั้งหมดและดูขอบเขตได้ที่ OAuth 2.0 Playground

ตัวอย่าง HTTP GET

การเรียกไปยังปลายทาง drive.files (Drive Files API) โดยใช้ส่วนหัว HTTP Authorization: Bearer อาจมีลักษณะดังต่อไปนี้ โปรดทราบว่าคุณต้องระบุโทเค็นเพื่อการเข้าถึงของคุณเอง ดังนี้

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

ต่อไปนี้เป็นการเรียก API เดียวกันสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้วโดยใช้พารามิเตอร์สตริงการค้นหา access_token

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

ตัวอย่างของ curl

คุณทดสอบคำสั่งเหล่านี้ได้ด้วยแอปพลิเคชันบรรทัดคำสั่ง curl ต่อไปนี้คือตัวอย่างที่ใช้ตัวเลือกส่วนหัว HTTP (แนะนำ)

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

หรือตัวเลือกพารามิเตอร์สตริงการค้นหา

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

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

หากต้องการรีเฟรชโทเค็นเพื่อการเข้าถึง แอปพลิเคชันของคุณจะส่งคำขอ HTTPS POST ไปยังเซิร์ฟเวอร์การให้สิทธิ์ของ Google (https://oauth2.googleapis.com/token) ซึ่งมีพารามิเตอร์ต่อไปนี้ในเนื้อหาคำขอ

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

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอ

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: DPOP_PROOF_JWT

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

หากต้องการใช้ DPoP กับโทเค็นการรีเฟรช คุณต้องสร้าง JWT หลักฐาน DPoP ใหม่ที่ไม่ซ้ำกันสำหรับคำขอ ดูสร้างการพิสูจน์ DPoP สำหรับวิธีการทีละขั้นตอนในการสร้างคู่คีย์และสร้าง JWT

การแลกเปลี่ยนที่สำเร็จจะแสดงด้วยการตอบกลับ 200 OK ที่มีโทเค็นเพื่อการเข้าถึงใหม่ เมื่อใช้ DPoP token_type จะเป็น Bearer การตอบกลับที่สำเร็จจะยืนยันว่าระบบยอมรับการพิสูจน์ DPoP สำหรับโทเค็นการรีเฟรช นอกจากนี้ Google อาจแสดงส่วนหัว HTTP DPoP-Nonce ใหม่ในการตอบกลับด้วย หากแสดง ไคลเอ็นต์ของคุณต้องแคช Nonce นี้และรวมไว้ในการอ้างสิทธิ์ nonce ของหลักฐาน DPoP ในคำขอต่อๆ ไป

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

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างส่วนหัวการตอบกลับและเนื้อหาที่สำเร็จเมื่อใช้ DPoP

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

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

การเพิกถอนโทเค็น

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

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

หากต้องการเพิกถอนโทเค็นแบบเป็นโปรแกรม แอปพลิเคชันของคุณจะส่งคำขอไปยัง https://oauth2.googleapis.com/revoke และรวมโทเค็นเป็นพารามิเตอร์ ดังนี้

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

โทเค็นอาจเป็นโทเค็นเพื่อการเข้าถึงหรือโทเค็นการรีเฟรชก็ได้ หากโทเค็นเป็นโทเค็นเพื่อการเข้าถึงและมีโทเค็นการรีเฟรชที่เกี่ยวข้อง ระบบจะเพิกถอนโทเค็นการรีเฟรชด้วย

หากการเพิกถอนได้รับการประมวลผลเรียบร้อยแล้ว รหัสสถานะ HTTP ของการตอบกลับจะเป็น 200 สำหรับเงื่อนไขข้อผิดพลาด ระบบจะแสดงรหัสสถานะ HTTP 400 พร้อมกับรหัสข้อผิดพลาด

วิธีการเปลี่ยนเส้นทางแอป

ปกป้องแอปของคุณ

การเข้าถึงตามเวลา

สิทธิ์เข้าถึงตามเวลาช่วยให้ผู้ใช้ให้สิทธิ์แอปเข้าถึงข้อมูลของตนเป็นระยะเวลาจำกัดเพื่อดำเนินการให้เสร็จสมบูรณ์ การเข้าถึงตามเวลาพร้อมใช้งานในผลิตภัณฑ์บางอย่างของ Google ในระหว่างขั้นตอนขอความยินยอม ซึ่งจะให้ตัวเลือกแก่ผู้ใช้ในการให้สิทธิ์เข้าถึงเป็นระยะเวลาที่จำกัด ตัวอย่างเช่น Data Portability API ซึ่งช่วยให้โอนข้อมูลได้แบบครั้งเดียว

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

อ่านเพิ่มเติม

แนวทางปฏิบัติที่ดีที่สุดในปัจจุบันของ IETF OAuth 2.0 สำหรับแอปที่มาพร้อมเครื่องได้กำหนดแนวทางปฏิบัติแนะนำหลายอย่างที่ระบุไว้ที่นี่