מנגנון 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 ולהשתמש בהיקפי גישה מוגבלים מפורטים יותר.

הענקת גישה ברמת הדומיין עבור

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

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

קובצי עזר