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 1 รายการเป็นค่าเริ่มต้นสำหรับชื่อแทนแต่ละรายการ
การให้สิทธิ์การเข้าถึง API
การให้สิทธิ์การเข้าถึง API มี 2 รูปแบบ ได้แก่
- คุณจะใช้บัญชีบริการกับการมอบสิทธิ์ทั่วทั้งโดเมนได้ ดูคำอธิบายข้อกำหนดเหล่านี้ได้ที่ข้อกำหนดภาพรวมของการตรวจสอบสิทธิ์และการให้สิทธิ์ โปรดดูข้อมูลเกี่ยวกับการเปิดใช้ตัวเลือกนี้ได้ที่สร้างบัญชีบริการที่มีการมอบสิทธิ์ทั่วทั้งโดเมน
- คุณสามารถใช้ขั้นตอน OAuth2 มาตรฐานที่ต้องได้รับความยินยอมจากผู้ใช้ปลายทางเพื่อรับโทเค็นเพื่อการเข้าถึง Oauth2 ได้ โปรดดูข้อมูลเพิ่มเติมที่ภาพรวมการตรวจสอบสิทธิ์และการให้สิทธิ์ หากต้องการใช้ตัวเลือกนี้ ผู้ดูแลระบบโดเมนต้องเปิดใช้ช่องทำเครื่องหมาย "เปิดใช้การเข้าถึงของผู้ใช้ปลายทาง S/MIME API แล้ว" ในแผงควบคุมโดเมน
ขอบเขต ACL
API นี้ใช้ขอบเขต ACL เดียวกันกับเมธอด Gmail sendAs ดังนี้
- gmail.settings.basic
- จำเป็นต้องมีขอบเขตนี้สำหรับการอัปเดต SendAs S/MIME หลัก
- gmail.settings.sharing
- จำเป็นต้องมีขอบเขตนี้เพื่ออัปเดต S/MIME ที่กำหนดเองจาก
การใช้ API
แหล่งข้อมูล users.settings.sendAs.smimeInfo มีเมธอดที่คุณใช้จัดการใบรับรอง S/MIME ใบรับรองแต่ละรายการจะเชื่อมโยงกับชื่อแทนที่ใช้ส่ง 1 ชื่อสำหรับผู้ใช้ 1 ราย
อัปโหลดคีย์ S/MIME
ใช้เมธอด smimeInfo.insert() เพื่ออัปโหลดคีย์ S/MIME ใหม่สำหรับชื่อแทนของผู้ใช้ คุณสามารถระบุชื่อแทนเป้าหมายโดยใช้พารามิเตอร์ต่อไปนี้
- userId
- อีเมลของผู้ใช้ คุณสามารถใช้ค่าพิเศษ
me
เพื่อระบุผู้ใช้ที่ตรวจสอบสิทธิ์แล้วในปัจจุบัน - sendAsEmail
- ชื่อแทนที่คุณกำลังอัปโหลดคีย์ นี่คือที่อยู่อีเมลที่ปรากฏในส่วนหัว "จาก:" สำหรับอีเมลที่ส่งโดยใช้ชื่อแทนนี้
ใบรับรอง S/MIME และคีย์ส่วนตัวควรแสดงอยู่ในช่อง pkcs12
ในรูปแบบดังกล่าว ไม่ควรมีการตั้งค่าช่องอื่นๆ ในคำขอ ช่อง PKCS12 ควรมีทั้งคีย์ S/MIME ของผู้ใช้และเชนใบรับรองการลงชื่อ API จะทำการตรวจสอบมาตรฐานในช่องนี้ก่อนที่จะยอมรับเพื่อยืนยันสิ่งต่อไปนี้
- เรื่องตรงกับอีเมลที่ระบุ
- วันหมดอายุถูกต้อง
- ผู้ออกใบรับรอง (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
รหัสตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้สาธิตการใช้ 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 ดังนี้
การจัดการใบรับรอง
ตัวอย่างนี้รวมการเรียกหลายรายการจาก smimeInfo
API เพื่อแสดงวิธีจัดการใบรับรองสำหรับองค์กร โดยจะแสดงใบรับรองสำหรับผู้ใช้ และหากใบรับรองเริ่มต้นหมดอายุหรือไม่ได้ตั้งค่า ระบบจะอัปโหลดใบรับรองที่พบในไฟล์ที่ระบุ จากนั้นระบบจะกำหนดใบรับรองที่มีวันหมดอายุไว้ให้ไกลที่สุดในอนาคตเป็นค่าเริ่มต้น
จากนั้นจะเรียกจากฟังก์ชันที่ประมวลผลไฟล์ CSV ดังเช่นในตัวอย่างก่อนหน้านี้