آلية 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 رمز Ctrl ‏+ 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") إلى التحدي الذي يحتوي على رسالة الخطأ.

المراجع