آلية OAuth 2.0

يحدد هذا المستند آلية SASL XOAUTH2 للاستخدام مع أوامر AUTHENTICATE IMAP و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 إلى الخادم. يستخدم البروتوكول القيم المشفرة المعروضة في الأقسام التالية.

استجابة العميل الاولى

تكون استجابة العميل الأولية XOAUTH2 بالتنسيق التالي:

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

استخدِم آلية ترميز base64 المحدّدة في RFC 4648. يمثل ^A عنصر تحكم +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.

استجابة العميل الاولى

لتسجيل الدخول باستخدام آلية XOAUTH2 لـ SASL، يستدعي العميل الأمر 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.

استجابة العميل الاولى

لتسجيل الدخول باستخدام آلية XOAUTH2 لـ SASL، يستدعي العميل الأمر 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 مع خادم Gmail 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:

  • تم توثيق الأمر AUTH لبروتوكول SMTP في 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") إلى التحدي الذي يحتوي على رسالة الخطأ.

المراجع