กลไก 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 มีดังนี้

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

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