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

מנגנון XOAUTH2 של SASL

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

  • פקודת IMAP AUTHENTICATE מתועדת ב-RFC 3501.
  • יכולת ה-SASL-IR מאפשרת לשלוח את תגובת הלקוח הראשונית בשורה הראשונה של הפקודה AUTHENTICATE, כך שנדרשת רק טיסה הלוך ושוב לצורך אימות. השימוש ב-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:

  • הפקודה AUTH של POP מתועדת ב-RFC 1734.
  • מעברי השורה בפקודה AUTH מיועדים לצורך הבהרה, ולא יופיעו בנתוני הפקודה בפועל. הארגומנט ב-base64 כולו צריך להיות מחרוזת רציפה אחת, ללא רווחים לבנים מוטמעים, כך שהפקודה AUTH כולה מכילה שורת טקסט אחת.

תגובת שגיאה

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

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

SMTP Protocol Exchange

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

קובצי עזר