מנגנון 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 מכיל שלושה ערכים: 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, כך שנדרש רק מסלול אחד הלוך ושוב לצורך אימות. ערך 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 עם שרת Gmail POP.

תגובה ראשונית ללקוח

כדי להתחבר באמצעות מנגנון SASL XOAUTH2, הלקוח מפעיל את הפקודה AUTH עם פרמטר המנגנון של XOAUTH2, והתשובה הראשונית של הלקוח כפי שנוצרה למעלה. לדוגמה:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

נקודות חשובות לגבי חילופי פרוטוקול POP:

  • הפקודה AUTH POP מתועדת ב-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') לאתגר שמכיל את הודעת השגיאה.

קובצי עזר