مکانیزم OAuth 2.0

این سند مکانیسم SASL XOAUTH2 را برای استفاده با دستورات IMAP AUTHENTICATE ، POP AUTH و SMTP AUTH تعریف می کند. این مکانیسم امکان استفاده از OAuth 2.0 Access Tokens را برای احراز هویت در حساب Gmail کاربر فراهم می کند.

با استفاده از OAuth 2.0

با آشنایی با استفاده از OAuth 2.0 برای دسترسی به APIهای Google شروع کنید. این سند نحوه عملکرد 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 represents 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 با سرور Gmail IMAP را توضیح می دهد.

پاسخ اولیه مشتری

برای ورود به سیستم با مکانیزم 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 با سرور Gmail POP را توضیح می دهد.

پاسخ مشتری اولیه

برای ورود با مکانیزم 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 از یک خط متن تشکیل شده باشد.

پاسخ به خطا

خرابی های احراز هویت نیز از طریق دستور 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 باید یک رشته پیوسته، بدون فضای خالی تعبیه شده باشد، به طوری که کل دستور 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") به چالش حاوی پیام خطا ارسال می کند.

مراجع