آلية 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 عنصر 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:

  • تم توثيق الأمر AUTH POP في 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:

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

المراجع