เอกสารนี้ระบุกลไก 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") ไปยังคำท้าที่มีข้อความแสดงข้อผิดพลาด
รายการอ้างอิง
- OAUTH2: การใช้ OAuth 2.0 เพื่อเข้าถึง Google API
- SMTP: RFC 2821: โปรโตคอลการถ่ายโอนอีเมลแบบง่าย
- IMAP: RFC 3501: โปรโตคอลการเข้าถึงข้อความทางอินเทอร์เน็ต - เวอร์ชัน 4rev1
- POP: RFC 1081: โปรโตคอลของที่ทำการไปรษณีย์ - เวอร์ชัน 3
- SASL: RFC 4422: การตรวจสอบสิทธิ์แบบง่ายและเลเยอร์ความปลอดภัย (SASL)
- JSON: RFC 4627: Application/json Media Type สำหรับสัญลักษณ์ออบเจ็กต์ JavaScript
- BASE64: RFC 4648: การเข้ารหัสข้อมูล Base16, Base32 และ Base64
- SASL-IR: RFC 4959: ส่วนขยาย IMAP สำหรับการตอบกลับไคลเอ็นต์เบื้องต้นและการตรวจสอบสิทธิ์แบบง่าย (SASL)
- SMTP-AUTH: RFC 4954: ส่วนขยายบริการ SMTP สำหรับการตรวจสอบสิทธิ์