กลไก 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 การมอบสิทธิ์ระดับโดเมน โดยใช้ บัญชีบริการ เพื่อเข้าถึงกล่องจดหมายของผู้ใช้ผ่าน IMAP คุณสามารถให้สิทธิ์ไคลเอ็นต์โดยใช้ขอบเขต https://www.googleapis.com/auth/gmail.imap_admin แทนได้ Google Workspace

เมื่อได้รับอนุญาตด้วยขอบเขตนี้ การเชื่อมต่อ 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 มีดังนี้

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

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