توفّر واجهة برمجة التطبيقات S/MIME في Gmail وصولاً آليًا لإدارة شهادات البريد الإلكتروني لـ S/MIME للمستخدمين في نطاق Google Workspace .
يجب على المشرف تفعيل S/MIME للنطاق لكي تعمل الشهادات.
يوفّر معيار S/MIME مواصفات لتشفير المفتاح العام وتوقيع بيانات MIME. يؤدي ضبط شهادات S/MIME في حساب مستخدم إلى استخدام Gmail لتلك الشهادة بالطرق التالية:
- يستخدم Gmail شهادة المستخدم والمفتاح الخاص لتوقيع البريد الصادر.
- يستخدم Gmail المفتاح الخاص للمستخدم لفك تشفير البريد الوارد.
- يستخدم Gmail شهادة المستلِم والمفتاح العام لتشفير البريد الصادر.
- يستخدم Gmail شهادة المرسل والمفتاح العام للتحقُّق من البريد الوارد.
ويمكنك إنشاء شهادات S/MIME فردية وتحميلها باستخدام واجهة برمجة التطبيقات. كل شهادة S/MIME مخصصة لاسم مستعار معين لحساب بريد إلكتروني للمستخدم. تتضمن الأسماء المستعارة عنوان البريد الإلكتروني الرئيسي بالإضافة إلى عناوين "الإرسال باسم" المخصصة. يتم وضع علامة على شهادة S/MIME واحدة كشهادة تلقائية لكل اسم مستعار.
تفويض الوصول إلى واجهة برمجة التطبيقات
هناك شكلان لتفويض الوصول إلى واجهة برمجة التطبيقات:
- يمكنك استخدام حساب خدمة مع تفويض مرجع على مستوى النطاق. لشرح هذه البنود، يُرجى الرجوع إلى بنود النظرة العامة على المصادقة والترخيص. للحصول على معلومات حول تفعيل هذا الخيار، يُرجى الاطّلاع على إنشاء حساب خدمة بتفويض مرجع على مستوى النطاق
- يمكنك استخدام مسار OAuth2 عادي يتطلب موافقة المستخدم للحصول على رمز دخول Oauth2. لمزيد من المعلومات، يُرجى الرجوع إلى نظرة عامة على المصادقة والتفويض لاستخدام هذا الخيار، على مشرف النطاق تفعيل مربّع الاختيار "تم تفعيل وصول المستخدم النهائي لواجهة برمجة تطبيقات S/MIME" في لوحة تحكُّم النطاق.
نطاقات قائمة التحكم بالوصول
تعتمد واجهة برمجة التطبيقات هذه على نطاقات ACL نفسها مثل طرق إرسال اسم المستخدم في Gmail:
- gmail.settings.basic
- هذا النطاق مطلوب لتعديل بيانات S/MIME الأساسية في SendAs.
- gmail.settings.sharing
- هذا النطاق مطلوب لتعديل من S/MIME المخصّص.
استخدام واجهة برمجة التطبيقات
يوفّر المورد users.settings.sendAs.smimeInfo الطرق التي تستخدمها لإدارة شهادات S/MIME. ترتبط كل شهادة باسم مستعار واحد للإرسال كاسم مستعار للمستخدم.
تحميل مفتاح S/MIME
استخدِم الإجراء smimeInfo.insert() لتحميل مفتاح S/MIME جديد لاسم مستعار ينتمي إلى مستخدم. يمكنك تحديد الاسم المستعار الهدف باستخدام المعلمات التالية:
- userId
- عنوان البريد الإلكتروني للمستخدِم يمكنك استخدام القيمة الخاصة
me
للإشارة إلى المستخدم الذي تمت مصادقته حاليًا. - sendAsEmail
- الاسم المستعار الذي يتم تحميل المفتاح له. وهذا هو عنوان البريد الإلكتروني الذي يظهر في العنوان "من:" للبريد المُرسَل باستخدام هذا العنوان البديل للبريد الإلكتروني.
يجب توفير شهادة S/MIME والمفتاح الخاص
في حقل pkcs12
بهذا التنسيق، ويجب عدم ضبط حقول أخرى
في الطلب. من المتوقع أن يحتوي حقل PKCS12 على كل من مفتاح S/MIME للمستخدم وسلسلة شهادات التوقيع. تُجري واجهة برمجة التطبيقات عمليات تحقق عادية في هذا الحقل قبل قبوله، والتحقق مما يلي:
- يتطابق الموضوع مع عنوان البريد الإلكتروني المحدّد.
- فترات انتهاء الصلاحية صالحة.
- مصدر الشهادة (CA) الذي أصدره موجود في قائمتنا الموثوق بها.
- تتطابق الشهادات مع قيود Gmail الفنية.
إذا كان المفتاح مشفّرًا، يجب أن تكون كلمة المرور في حقل encryptedKeyPassword
. ستعرض عمليات استدعاء Insert() بنجاح معرّف smimeInfo الذي يمكن استخدامه للإشارة إلى المفتاح في المستقبل.
إدراج مفاتيح S/MIME لمستخدم
استخدِم الإجراء smimeInfo.list() لعرض قائمة مفاتيح S/MIME للمستخدم المحدَّد للاسم المستعار المحدَّد. يمكنك تحديد الاسم المستعار الهدف باستخدام المعلمات التالية:
- userId
- عنوان البريد الإلكتروني للمستخدِم يمكنك استخدام القيمة الخاصة
me
للإشارة إلى المستخدم الذي تمت مصادقته حاليًا. - sendAsEmail
- الاسم المستعار المراد إدراج مفاتيح له. وهذا هو عنوان البريد الإلكتروني الذي يظهر في العنوان "من:" للبريد المُرسَل باستخدام هذا العنوان البديل للبريد الإلكتروني.
استرداد مفاتيح S/MIME لاسم مستعار
استخدِم الطريقة smimeInfo.get() لعرض مفاتيح S/MIME المحدّدة لاسم مستعار معيّن لإرساله لمستخدم معيّن. يمكنك تحديد الاسم المستعار الهدف باستخدام المعلمات التالية:
- userId
- عنوان البريد الإلكتروني للمستخدِم يمكنك استخدام القيمة الخاصة
me
للإشارة إلى المستخدم الذي تمت مصادقته حاليًا. - sendAsEmail
- الاسم المستعار الذي تستردّ المفاتيح له. وهذا هو عنوان البريد الإلكتروني الذي يظهر في العنوان "من:" للبريد المُرسَل باستخدام هذا العنوان البديل للبريد الإلكتروني.
حذف مفتاح S/MIME
استخدِم الإجراء smimeInfo.delete() لحذف مفتاح S/MIME المحدّد من اسم مستعار. يمكنك تحديد الاسم المستعار الهدف باستخدام المعلمات التالية:
- userId
- عنوان البريد الإلكتروني للمستخدِم يمكنك استخدام القيمة الخاصة
me
للإشارة إلى المستخدم الذي تمت مصادقته حاليًا. - sendAsEmail
- الاسم المستعار الذي تستردّ المفاتيح له. هذا هو عنوان البريد الإلكتروني الذي يظهر في العنوان "من:" للرسائل الإلكترونية المُرسَلة باستخدام هذا العنوان البديل للبريد الإلكتروني.
- id
- المعرّف غير القابل للتغيير لـ SmimeInfo
ضبط مفتاح S/MIME التلقائي لاسم مستعار
استخدِم الطريقة smimeInfo.setDefault() لوضع علامة على مفتاح S/MIME المحدَّد كمفتاح تلقائي للاسم المستعار المحدَّد. يمكنك تحديد الاسم المستعار الهدف باستخدام المعلمات التالية:
- userId
- عنوان البريد الإلكتروني للمستخدِم يمكنك استخدام القيمة الخاصة
me
للإشارة إلى المستخدم الذي تمت مصادقته حاليًا. - sendAsEmail
- الاسم المستعار الذي تستردّ المفاتيح له. هذا هو عنوان البريد الإلكتروني الذي يظهر في العنوان "من:" للرسائل الإلكترونية المُرسَلة باستخدام هذا العنوان البديل للبريد الإلكتروني.
- id
- المعرّف غير القابل للتغيير لـ SmimeInfo
نموذج التعليمات البرمجية
توضّح نماذج الرموز التالية استخدام واجهة برمجة التطبيقات لإدارة شهادات S/MIME لمؤسسة تتضمّن عدة مستخدمين.
إنشاء مورد SmimeInfo لشهادة S/MIME
يوضح نموذج الرمز البرمجي التالي قراءة شهادة من الملف، وترميزها إلى سلسلة base64url، وتعيينها للحقل pkcs12
في المورد smimeInfo
:
Java
Python
تحميل شهادة S/MIME
لتحميل شهادة، اطلب الرمز
smimeInfo.insert
وقدِّم مورد smimeInfo
في نص الطلب:
Java
Python
أمثلة لإدارة شهادات العديد من المستخدمين
قد ترغب في إدارة الشهادات للعديد من المستخدمين في المؤسسة في آنٍ واحد. توضّح الأمثلة التالية كيفية إدارة الشهادات لعدة مستخدمين في مكالمة جماعية واحدة.
إدراج شهادات من ملف CSV
لنفترض أن لديك ملف CSV يسرد أرقام تعريف المستخدمين والمسار إلى شهادة كل مستخدم:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
يمكنك الاستفادة من طلبَي createSmimeInfo
وinsertSmimeInfo
السابقَين لتحميل الشهادات كما هو محدّد في ملف CSV:
Python
يمكنك الاستفادة من طلبَي create_smime_info
وinsert_smime_info
السابقَين لتحميل الشهادات كما هو محدّد في ملف CSV:
إدارة الشهادات
يدمج هذا المثال عدة طلبات من واجهة برمجة التطبيقات smimeInfo
لعرض الطريقة التي يمكنك من خلالها
إدارة الشهادات لمؤسستك. فهي تعرض الشهادات للمستخدم،
وإذا انتهت صلاحية الشهادة التلقائية أو لم يتم ضبطها، تُحمِّل الشهادة التي تم العثور عليها في
الملف المحدَّد. ثم يتم ضبط الشهادة التي يقع تاريخ انتهاء صلاحيتها في المستقبل
كإعداد تلقائي للشهادة.
ثم يتم استدعاء هذا من دالة تعالج ملف CSV كما في المثال السابق.