آلية 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.

آلية 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 مع خادم 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 بأكمله من سطر نص واحد.

ردّ الخطأ

يتم أيضًا عرض أخطاء المصادقة من خلال الأمر 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:

  • تم توثيق الأمر 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") إلى التحدّي الذي يتضمّن رسالة الخطأ.

المراجع