Gmail S/MIME API מספק גישה פרוגרמטית לניהול אישורי S/MIME לאימייל עבור משתמשים בדומיין Google Workspace .
כדי שהאישורים יפעלו, האדמין צריך להפעיל S/MIME בדומיין.
תקן S/MIME מספק מפרט להצפנת מפתחות ציבוריים ולחתימה של נתוני MIME. הגדרה של אישורי S/MIME בחשבון משתמש גורמת ל-Gmail להשתמש באישור הזה בדרכים הבאות:
- Gmail משתמש באישור ובמפתח הפרטי של המשתמש כדי לחתום על דואר יוצא.
- Gmail משתמש במפתח הפרטי של המשתמש כדי לפענח הודעות אימייל נכנסות.
- Gmail משתמש באישור ובמפתח הציבורי של הנמען כדי להצפין דואר יוצא.
- Gmail משתמש באישור השולח ובמפתח הציבורי כדי לאמת דואר נכנס.
יוצרים אישורי S/MIME בודדים ומעלים אותם באמצעות ה-API. כל אישור S/MIME מיועד לכתובת אימייל חלופית ספציפית לחשבון אימייל של משתמש. כינויים כוללים את כתובת האימייל הראשית וכן כתובות מותאמות אישית מסוג 'שליחה בשם'. אישור S/MIME יחיד מסומן כברירת המחדל עבור כל כינוי.
הרשאת גישה ל-API
יש שתי צורות של הרשאת גישה ל-API:
- אפשר להשתמש בחשבון שירות עם הענקת סמכויות ברמת הדומיין. למידע נוסף על התנאים האלה, קראו את המאמר סקירה כללית על אימות והרשאות. למידע על הפעלת האפשרות הזו, ראו יצירת חשבון שירות עם הענקת סמכויות ברמת הדומיין
- אפשר להשתמש בתהליך OAuth2 סטנדרטי שבו נדרשת הסכמה ממשתמשי הקצה לקבל אסימון גישה ל-Oauth2. למידע נוסף, אפשר לעיין בסקירה הכללית על אימות והרשאות כדי להשתמש באפשרות הזו, על מנהל הדומיין להפעיל את תיבת הסימון 'S/MIME API end user access enabled' בלוח הבקרה של הדומיין.
היקפי ACL
ה-API הזה מסתמך על אותם היקפים של ACL בשיטות sendAs ב-Gmail:
- gmail.settings.basic
- ההיקף הזה נדרש לעדכון ה-S/MIME הראשי של SendAs.
- gmail.settings.sharing
- ההיקף הזה נדרש לעדכון S/MIME מותאם אישית מתוך.
שימוש ב-API
במשאב users.settings.sendAs.smimeInfo אפשר למצוא את השיטות שמשמשות לניהול אישורי S/MIME. כל אישור משויך לכתובת אימייל חלופית אחת שנשלחת עבור משתמש.
העלאה של מפתח S/MIME
משתמשים בשיטה smimeInfo.insert() כדי להעלות מפתח S/MIME חדש לכתובת אימייל חלופית ששייכת למשתמש. את כינוי היעד אפשר לזהות באמצעות הפרמטרים הבאים:
- userId
- כתובת האימייל של המשתמש. אפשר להשתמש בערך המיוחד
me
כדי לציין את המשתמש המאומת הנוכחי. - sendAsEmail
- הכינוי שעבורו אתם מעלים את המפתח. זוהי כתובת האימייל שמופיעה בכותרת 'מאת:' בהודעות שנשלחות באמצעות כתובת האימייל החלופית.
אישור ה-S/MIME והמפתח הפרטי צריכים להופיע בשדה pkcs12
בפורמט הזה, ולא צריך להגדיר שדות אחרים בבקשה. השדה PKCS12 אמור להכיל את מפתח ה-S/MIME של המשתמש וגם את שרשרת האישורים לחתימה. ה-API מבצע אימותים סטנדרטיים בשדה הזה לפני שהוא מאשר אותו, ומאמת את הפרטים הבאים:
- הנושא תואם לכתובת האימייל שצוינה.
- התוקף של תאריכי התפוגה.
- רשות האישורים המנפיקה נמצאת ברשימת המהימנות שלנו.
- האישורים תואמים למגבלות הטכניות של Gmail.
אם המפתח מוצפן, הסיסמה צריכה להיות בשדה encryptedKeyPassword
. קריאות מסוג Insert() שבוצעו בהצלחה יחזירו את המזהה של smimeInfo שאפשר להשתמש בו כדי להפנות למפתח בעתיד.
הצגת רשימה של מפתחות S/MIME של המשתמש
משתמשים בשיטה smimeInfo.list() כדי להחזיר את רשימת מפתחות ה-S/MIME של המשתמש הנתון בכינוי הנתון. את כינוי היעד אפשר לזהות באמצעות הפרמטרים הבאים:
- userId
- כתובת האימייל של המשתמש. אפשר להשתמש בערך המיוחד
me
כדי לציין את המשתמש המאומת הנוכחי. - sendAsEmail
- הכינוי שעבורו יש לרשום את המפתחות. זוהי כתובת האימייל שמופיעה בכותרת 'מאת:' בהודעות שנשלחות באמצעות כתובת האימייל החלופית.
אחזור מפתחות S/MIME של כינוי
משתמשים בשיטה smimeInfo.get() כדי להחזיר את מפתחות ה-S/MIME הספציפיים לכינוי ספציפי בפורמט send-as עבור משתמש. את כינוי היעד אפשר לזהות באמצעות הפרמטרים הבאים:
- 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.
קוד לדוגמה
בדוגמאות הקוד הבאות אפשר להשתמש ב-API לניהול אישורי 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:
ניהול אישורים
הדוגמה הזו משלבת מספר קריאות מה-API של smimeInfo
, כדי להמחיש איך אפשר לנהל את האישורים של הארגון. ברשימה מופיעים האישורים של המשתמש, ואם אישור ברירת המחדל כבר לא בתוקף או לא מוגדר, הוא מעלה את האישור שנמצא בקובץ שצוין. לאחר מכן היא מגדירה כברירת מחדל את האישור שהתוקף שלו יפוג בעתיד.
הוא נקרא לאחר מכן מפונקציה שמעבדת קובץ CSV כמו בדוגמה הקודמת.