กลไก 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 และใช้ขอบเขตที่จำกัดที่ละเอียดยิ่งขึ้น

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

หากต้องการใช้Google Workspace การมอบสิทธิ์ทั่วทั้งโดเมน โดยใช้ บัญชีบริการ เพื่อเข้าถึง Google Workspace กล่องจดหมายของผู้ใช้ผ่าน 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")

ใช้กลไกการเข้ารหัส base64 ที่กำหนดไว้ใน 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

  • คำสั่ง IMAP AUTHENTICATE บันทึกไว้ใน RFC 3501
  • ความสามารถ SASL-IR ช่วยให้ส่งการตอบกลับเริ่มต้นของไคลเอ็นต์ในบรรทัดแรกของคำสั่ง AUTHENTICATE ได้ จึงต้องมีการส่งข้อมูลไป-กลับเพียงครั้งเดียวสำหรับการตรวจสอบสิทธิ์ SASL-IR จัดทำเป็นเอกสารใน RFC 4959
  • ความสามารถ AUTH=XOAUTH2 จะประกาศว่าเซิร์ฟเวอร์สนับสนุนกลไก SASL ที่กำหนดโดยเอกสารนี้ และเปิดใช้งานกลไกนี้โดยระบุ XOAUTH2 เป็นอาร์กิวเมนต์แรกสำหรับคำสั่ง AUTHENTICATE
  • การขึ้นบรรทัดใหม่ในคำสั่ง AUTHENTICATE และ CAPABILITY มีไว้เพื่อความชัดเจนและจะไม่แสดงในข้อมูลคำสั่งจริง อาร์กิวเมนต์ base64 ทั้งหมดควรเป็นสตริงต่อเนื่อง 1 สตริงโดยไม่มีช่องว่างแบบฝัง เพื่อให้คำสั่ง 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 ทั้งหมดควรเป็นสตริงต่อเนื่อง 1 สตริงโดยไม่มีช่องว่างแบบฝัง เพื่อให้คำสั่ง 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 ทั้งหมดควรเป็นสตริงต่อเนื่อง 1 สตริงโดยไม่มีช่องว่างแบบฝัง เพื่อให้คำสั่ง 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") ไปยังคำท้าที่มีข้อความแสดงข้อผิดพลาด

รายการอ้างอิง