กลไก OAuth 2.0

เอกสารนี้กำหนดกลไก SASL XOAUTH2 เพื่อใช้กับคำสั่ง IMAP AUTHENTICATE, POP AUTH และ SMTP AUTH กลไกนี้ช่วยให้ใช้โทเค็นการเข้าถึง OAuth 2.0 เพื่อตรวจสอบสิทธิ์ในบัญชี Gmail ของผู้ใช้ได้

การใช้ OAuth 2.0

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

นอกจากนี้ คุณยังอาจต้องการเรียกดูโค้ด XOAUTH2 ตัวอย่างเพื่อดูตัวอย่างที่ใช้งานได้

ขอบเขต OAuth 2.0

ขอบเขตการเข้าถึง IMAP, POP และ SMTP คือ https://mail.google.com/ หากคุณขอสิทธิ์เข้าถึงขอบเขตอีเมลทั้งหมดสําหรับแอป IMAP, POP หรือ SMTP แอปดังกล่าวต้องเป็นไปตามบริการ Google API: นโยบายข้อมูลผู้ใช้

  • แอปของคุณต้องแสดงให้เห็นถึงการใช้งาน https://mail.google.com/ อย่างเต็มรูปแบบจึงจะได้รับอนุมัติ
  • หากแอปของคุณไม่จําเป็นต้องใช้ https://mail.google.com/ ให้ย้ายข้อมูลไปยัง Gmail API และใช้ขอบเขตที่จํากัดที่ละเอียดยิ่งขึ้น

การมอบสิทธิ์ทั่วทั้งโดเมนสำหรับ

หากต้องการใช้ การมอบสิทธิ์ทั่วทั้งโดเมนโดยใช้บัญชีบริการเพื่อเข้าถึง กล่องจดหมายของผู้ใช้ผ่าน IMAP ให้สิทธิ์ไคลเอ็นต์โดยใช้ขอบเขต https://www.googleapis.com/auth/gmail.imap_admin แทน

เมื่อได้รับสิทธิ์ด้วยขอบเขตนี้ การเชื่อมต่อ IMAP จะทำงานแตกต่างกันดังนี้

  • ป้ายกำกับทั้งหมดจะแสดงผ่าน IMAP แม้ว่าผู้ใช้จะปิดใช้ "แสดงใน IMAP" สำหรับป้ายกำกับนั้นในการตั้งค่า Gmail ก็ตาม
  • ข้อความทั้งหมดจะแสดงผ่าน IMAP ไม่ว่าผู้ใช้จะตั้งค่า "ขีดจำกัดขนาดโฟลเดอร์" ในการตั้งค่า Gmail ไว้อย่างไรก็ตาม

กลไก SASL XOAUTH2

กลไก XOAUTH2 ช่วยให้ไคลเอ็นต์ส่งโทเค็นการเข้าถึง OAuth 2.0 ไปยังเซิร์ฟเวอร์ได้ โปรโตคอลใช้ค่าที่เข้ารหัสซึ่งแสดงในส่วนต่อไปนี้

การตอบกลับครั้งแรกของลูกค้า

การตอบกลับครั้งแรกของไคลเอ็นต์ SASL XOAUTH2 มีรูปแบบดังนี้

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

ใช้กลไกการเข้ารหัสฐาน 64 ที่ระบุไว้ใน RFC 4648 ^A แสดงถึงแป้น Control+A (\001)

ตัวอย่างเช่น ก่อนการเข้ารหัส Base64 การตอบกลับเริ่มต้นของไคลเอ็นต์อาจมีลักษณะดังนี้

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

หลังจากการเข้ารหัส Base64 ข้อความจะกลายเป็น (มีการแทรกการแบ่งบรรทัดเพื่อความชัดเจน)

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

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

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

base64({JSON-Body})

JSON-Body มี 3 ค่า ได้แก่ status, schemes และ scope เช่น

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

หลังจากการถอดรหัส Base64 ข้อความจะกลายเป็น (จัดรูปแบบเพื่อความชัดเจน)

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

โปรโตคอล SASL กําหนดให้ไคลเอ็นต์ส่งการตอบกลับที่ว่างเปล่าสําหรับคําท้านี้

การแลกเปลี่ยนโปรโตคอล IMAP

ส่วนนี้จะอธิบายวิธีใช้ SASL XOAUTH2 กับเซิร์ฟเวอร์ IMAP ของ Gmail

การตอบกลับครั้งแรกของลูกค้า

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

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]

สิ่งที่ควรทราบเกี่ยวกับการแลกเปลี่ยนโปรโตคอล IMAP

  • คำสั่ง AUTHENTICATE ของ IMAP มีอยู่ในเอกสาร RFC 3501
  • ความสามารถของ SASL-IR ช่วยให้ส่งการตอบกลับเริ่มต้นของไคลเอ็นต์ได้ในบรรทัดแรกของคําสั่ง AUTHENTICATE เพื่อให้ใช้การไปกลับเพียงครั้งเดียวในการรับรอง SASL-IR มีเอกสารประกอบอยู่ใน RFC 4959
  • ความสามารถ AUTH=XOAUTH2 ประกาศว่าเซิร์ฟเวอร์รองรับกลไก SASL ที่ระบุไว้ในเอกสารนี้ และกลไกนี้จะเปิดใช้งานโดยการระบุ XOAUTH2 เป็นอาร์กิวเมนต์แรกในคำสั่ง AUTHENTICATE
  • การแบ่งบรรทัดในคําสั่ง AUTHENTICATE และ CAPABILITY มีไว้เพื่อความชัดเจนและจะไม่ปรากฏในข้อมูลคําสั่งจริง อาร์กิวเมนต์ Base64 ทั้งหมดควรเป็นสตริงต่อเนื่องยาวๆ รายการเดียวโดยไม่มีช่องว่างแทรกอยู่ เพื่อให้คำสั่ง AUTHENTICATE ทั้งหมดประกอบด้วยข้อความบรรทัดเดียว

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

ระบบจะแสดงผลการตรวจสอบสิทธิ์ที่ไม่สําเร็จผ่านคําสั่ง IMAP AUTHENTICATE ด้วย

[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed

สิ่งที่ควรทราบเกี่ยวกับการแลกเปลี่ยนโปรโตคอล IMAP

  • ไคลเอ็นต์ส่งการตอบกลับที่ว่างเปล่า ("\r\n") ไปยังคำขอยืนยันที่มีข้อความแสดงข้อผิดพลาด

การแลกเปลี่ยนโปรโตคอล POP

ส่วนนี้จะอธิบายวิธีใช้ SASL XOAUTH2 กับเซิร์ฟเวอร์ POP ของ Gmail

การตอบกลับครั้งแรกของลูกค้า

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

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

สิ่งที่ควรทราบเกี่ยวกับการแลกเปลี่ยนโปรโตคอล POP

  • คำสั่ง POP AUTH มีอยู่ในเอกสาร RFC 1734
  • การแบ่งบรรทัดในคําสั่ง AUTH มีไว้เพื่อความชัดเจนและจะไม่ปรากฏในข้อมูลคําสั่งจริง อาร์กิวเมนต์ Base64 ทั้งหมดควรเป็นสตริงต่อเนื่องยาวๆ รายการเดียวโดยไม่มีช่องว่างแทรกอยู่ เพื่อให้คำสั่ง AUTH ทั้งหมดประกอบด้วยข้อความบรรทัดเดียว

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

ระบบจะแสดงผลการตรวจสอบสิทธิ์ที่ไม่สําเร็จผ่านคําสั่ง POP AUTH ด้วย

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

การแลกเปลี่ยนโปรโตคอล SMTP

ส่วนนี้จะอธิบายวิธีใช้ SASL XOAUTH2 กับเซิร์ฟเวอร์ SMTP ของ Gmail

การตอบกลับครั้งแรกของลูกค้า

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

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]

สิ่งที่ควรทราบเกี่ยวกับการแลกเปลี่ยนโปรโตคอล SMTP

  • คำสั่ง SMTP AUTH มีเอกสารประกอบอยู่ใน RFC 4954
  • การแบ่งบรรทัดในคําสั่ง AUTH มีไว้เพื่อความชัดเจนและจะไม่ปรากฏในข้อมูลคําสั่งจริง อาร์กิวเมนต์ Base64 ทั้งหมดควรเป็นสตริงต่อเนื่องยาวๆ รายการเดียวโดยไม่มีช่องว่างแทรกอยู่ เพื่อให้คำสั่ง AUTH ทั้งหมดประกอบด้วยข้อความบรรทัดเดียว

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

ระบบจะแสดงผลการตรวจสอบสิทธิ์ที่ไม่สําเร็จผ่านคําสั่ง SMTP AUTH ด้วย

[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]

สิ่งที่ควรทราบเกี่ยวกับการแลกเปลี่ยนโปรโตคอล SMTP

  • ไคลเอ็นต์ส่งการตอบกลับที่ว่างเปล่า ("\r\n") ไปยังคำขอยืนยันที่มีข้อความแสดงข้อผิดพลาด

ข้อมูลอ้างอิง