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

المراجع