آلية 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 واستخدام نطاقات مشروطة أكثر دقة.

التفويض على مستوى النطاق لنطاق 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 يمثّل عنصر تحكّم +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:

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

المراجع