กลไก OAuth 2.0

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

การใช้ OAuth 2.0

เริ่มต้นด้วยการอ่านการใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs เอกสารดังกล่าวอธิบายวิธีการทำงานของ 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 ทั้งหมด ควรเป็นสตริงต่อเนื่องเดียวโดยไม่มีช่องว่างฝังอยู่ เพื่อให้ คำสั่ง 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 มีดังนี้

  • คำสั่ง AUTH SMTP มีอยู่ใน 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") ไปยังคำท้าที่มี ข้อความแสดงข้อผิดพลาด

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