يحدِّد هذا المستند آلية 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 واستخدام نطاقات محدودة أكثر دقة.
التفويض على مستوى النطاق في
إذا كنت تنوي استخدام
تفويض على مستوى النطاق
باستخدام
حسابات الخدمة
للوصول إلى مكبّرات البريد الإلكتروني للمستخدمين عبر بروتوكول 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:
- تم توثيق الأمر IMAP
AUTHENTICATE
في 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") إلى طلب التحقّق الذي يحتوي على رسالة الخطأ.
المراجع
- OAUTH2: استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs
- بروتوكول SMTP: RFC 2821: بروتوكول نقل البريد البسيط
- بروتوكول IMAP: RFC 3501: بروتوكول الوصول إلى رسائل الإنترنت، الإصدار 4rev1
- بروتوكول POP: RFC 1081: Post Office Protocol - Version 3
- بروتوكول SASL: RFC 4422: طبقة الأمان والمصادقة البسيطة (SASL)
- تنسيق JSON: RFC 4627: نوع الوسائط application/json لتنسيق JavaScript Object Notation
- BASE64: RFC 4648: ترميزات البيانات Base16 وBase32 وBase64
- SASL-IR: RFC 4959: إضافة IMAP لطبقة الأمان والمصادقة البسيطة (SASL) لردّ العميل الأوّلي
- SMTP-AUTH: RFC 4954: SMTP Service Extension for Authentication