مکانیزم OAuth 2.0

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

استفاده از OAuth 2.0

با آشنایی با «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» شروع کنید. این سند نحوه کار OAuth 2.0 و مراحل لازم برای نوشتن یک کلاینت را توضیح می‌دهد.

همچنین می‌توانید برای مشاهده‌ی مثال‌های کاربردی، کد نمونه‌ی XOAUTH2 را مرور کنید.

دامنه‌های OAuth 2.0

دامنه دسترسی IMAP، POP و SMTP https://mail.google.com/ است. اگر درخواست دسترسی به کل دامنه ایمیل برای برنامه IMAP، POP یا SMTP خود را دارید، باید با خدمات API گوگل ما: خط‌مشی داده‌های کاربر مطابقت داشته باشد.

  • برای تأیید، برنامه شما باید استفاده کامل از https://mail.google.com/ را نشان دهد.
  • اگر برنامه شما به https://mail.google.com/ نیاز ندارد، به API جیمیل مهاجرت کنید و از محدوده‌های محدودتر و جزئی‌تری استفاده کنید.

واگذاری اختیار در سطح دامنه برای Google Workspace

اگر قصد دارید از واگذاری اختیارات در سطح دامنه Google Workspace با استفاده از حساب‌های سرویس برای دسترسی به صندوق‌های پستی کاربران Google Workspace از طریق IMAP استفاده کنید، می‌توانید به جای آن، کلاینت خود را با استفاده از دامنه https://www.googleapis.com/auth/gmail.imap_admin مجاز کنید.

وقتی با این دامنه مجاز شوید، اتصالات IMAP رفتار متفاوتی دارند:

  • همه برچسب‌ها از طریق IMAP نمایش داده می‌شوند، حتی اگر کاربران گزینه «نمایش در IMAP» را برای برچسب در تنظیمات Gmail غیرفعال کرده باشند.
  • صرف نظر از اینکه کاربر در تنظیمات Gmail در قسمت «محدودیت اندازه پوشه» چه تنظیماتی انجام داده باشد، همه پیام‌ها از طریق IMAP نمایش داده می‌شوند.

مکانیسم 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 با سرور 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 جیمیل را توضیح می‌دهد.

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

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

منابع