מנגנון 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

אם אתם מתכוונים להשתמש בהענקת גישה ברמת הדומיין באמצעות חשבונות שירות כדי לגשת לתיבות הדואר של המשתמשים דרך IMAP, אתם יכולים להעניק הרשאה ללקוח באמצעות ההיקף https://www.googleapis.com/auth/gmail.imap_admin במקום זאת.Google Workspace 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 מכיל שלושה ערכים: status,‏ schemes ו-scope. לדוגמה:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

אחרי פענוח בקידוד base64, המחרוזת הזו הופכת ל-(הפורמט הוא להמחשה):

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

פרוטוקול SASL מחייב את הלקוחות לשלוח תגובה ריקה לאתגר הזה.

פרוטוקול IMAP Exchange

בקטע הזה מוסבר איך להשתמש ב-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 תורכב משורה אחת של טקסט.

תשובת שגיאה

כשלים באימות מוחזרים גם באמצעות הפקודה AUTHENTICATE של IMAP:

[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 תורכב משורה אחת של טקסט.

תשובת שגיאה

כשלים באימות מוחזרים גם באמצעות הפקודה AUTH של POP:

[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 תורכב משורה אחת של טקסט.

תשובת שגיאה

כשלים באימות מוחזרים גם באמצעות הפקודה AUTH של SMTP:

[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") לאתגר שמכיל את הודעת השגיאה.

קובצי עזר