Gmail S/MIME API menyediakan akses terprogram untuk mengelola sertifikat email S/MIME bagi pengguna di domain Google Workspace.
Administrator harus mengaktifkan S/MIME untuk domain agar sertifikat dapat berfungsi.
Standar S/MIME memberikan spesifikasi untuk enkripsi kunci publik dan penandatanganan data MIME. Mengonfigurasi sertifikat S/MIME di akun pengguna menyebabkan Gmail menggunakan sertifikat tersebut dengan cara berikut:
- Gmail menggunakan sertifikat dan kunci pribadi pengguna untuk menandatangani email keluar.
- Gmail menggunakan kunci pribadi pengguna untuk mendekripsi email masuk.
- Gmail menggunakan sertifikat dan kunci publik penerima untuk mengenkripsi email keluar.
- Gmail menggunakan sertifikat dan kunci publik pengirim untuk memverifikasi email masuk.
Anda membuat sertifikat S/MIME individual dan menguploadnya menggunakan API. Setiap sertifikat S/MIME ditujukan untuk alias tertentu dari akun email pengguna. Alias mencakup alamat email utama serta alamat "Kirim Sebagai" khusus. Satu sertifikat S/MIME ditandai sebagai default untuk setiap alias.
Mengizinkan akses API
Ada dua bentuk pemberian otorisasi akses ke API:
- Anda dapat menggunakan akun layanan dengan delegasi kewenangan seluruh domain. Untuk penjelasan istilah ini, lihat Istilah ringkasan autentikasi dan otorisasi. Untuk mengetahui informasi tentang cara mengaktifkan opsi ini, lihat Membuat akun layanan dengan pendelegasian kewenangan ke seluruh domain
- Anda dapat menggunakan alur OAuth2 standar yang memerlukan izin pengguna akhir untuk mendapatkan token akses OAuth2. Untuk mengetahui informasi lebih lanjut, lihat Ringkasan autentikasi dan otorisasi Untuk menggunakan opsi ini, admin domain harus mencentang kotak "Akses pengguna akhir S/MIME API diaktifkan" di panel kontrol Domain.
Cakupan ACL
API ini mengandalkan cakupan ACL yang sama dengan metode Gmail sendAs:
- gmail.settings.basic
- Cakupan ini diperlukan untuk memperbarui S/MIME KirimSebagai utama.
- gmail.settings.sharing
- Cakupan ini diperlukan untuk memperbarui dari S/MIME kustom.
Menggunakan API
Resource users.settings.sendAs.smimeInfo menyediakan metode yang Anda gunakan untuk mengelola sertifikat S/MIME. Setiap sertifikat dikaitkan dengan satu alias kirim sebagai untuk pengguna.
Mengupload kunci S/MIME
Gunakan metode smimeInfo.insert() untuk mengupload kunci S/MIME baru untuk alias milik pengguna. Anda mengidentifikasi alias target menggunakan parameter berikut:
- userId
- Alamat email pengguna. Anda dapat menggunakan nilai khusus
me
untuk menunjukkan pengguna yang saat ini diautentikasi. - sendAsEmail
- Alias tempat Anda mengupload kunci. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
Sertifikat S/MIME dan kunci pribadi harus ada di kolom pkcs12
dalam format tersebut; tidak ada kolom lain yang boleh ditetapkan dalam permintaan. Kolom PKCS12 diharapkan berisi kunci S/MIME pengguna dan rantai sertifikat penandatanganan. API melakukan validasi standar pada kolom ini sebelum menerimanya, dengan memverifikasi hal berikut:
- Subjek cocok dengan alamat email yang ditentukan.
- Masa berlaku valid.
- Certificate authority (CA) penerbit ada dalam daftar tepercaya kami.
- Sertifikat sesuai dengan batasan teknis Gmail.
Jika kunci dienkripsi, sandi harus ada di kolom encryptedKeyPassword
. Panggilan insert() yang berhasil akan menampilkan ID smimeInfo yang dapat digunakan untuk merujuk ke kunci pada masa mendatang.
Mencantumkan kunci S/MIME pengguna
Gunakan metode smimeInfo.list() untuk menampilkan daftar kunci S/MIME untuk pengguna tertentu dan alias tertentu. Anda mengidentifikasi alias target menggunakan parameter berikut:
- userId
- Alamat email pengguna. Anda dapat menggunakan nilai khusus
me
untuk menunjukkan pengguna yang saat ini diautentikasi. - sendAsEmail
- Alias yang akan digunakan untuk mencantumkan kunci. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
Mengambil kunci S/MIME untuk alias
Gunakan metode smimeInfo.get() untuk menampilkan kunci S/MIME tertentu untuk alias kirim sebagai tertentu bagi pengguna. Anda mengidentifikasi alias target menggunakan parameter berikut:
- userId
- Alamat email pengguna. Anda dapat menggunakan nilai khusus
me
untuk menunjukkan pengguna yang saat ini diautentikasi. - sendAsEmail
- Alias yang kuncinya Anda ambil. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
Menghapus kunci S/MIME
Gunakan metode smimeInfo.delete() untuk menghapus kunci S/MIME tertentu dari alias. Anda mengidentifikasi alias target menggunakan parameter berikut:
- userId
- Alamat email pengguna. Anda dapat menggunakan nilai khusus
me
untuk menunjukkan pengguna yang saat ini diautentikasi. - sendAsEmail
- Alias yang kuncinya Anda ambil. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
- id
- ID yang tidak dapat diubah untuk SmimeInfo.
Menetapkan kunci S/MIME default untuk alias
Gunakan metode smimeInfo.setDefault() untuk menandai kunci S/MIME tertentu sebagai default untuk alias tertentu. Anda mengidentifikasi alias target menggunakan parameter berikut:
- userId
- Alamat email pengguna. Anda dapat menggunakan nilai khusus
me
untuk menunjukkan pengguna yang saat ini diautentikasi. - sendAsEmail
- Alias yang kuncinya Anda ambil. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
- id
- ID yang tidak dapat diubah untuk SmimeInfo.
Kode contoh
Contoh kode berikut menunjukkan penggunaan API untuk mengelola sertifikat S/MIME bagi organisasi dengan beberapa pengguna.
Membuat resource SmimeInfo untuk sertifikat S/MIME
Contoh kode berikut menunjukkan cara membaca sertifikat dari file, mengenkode
ke string base64url, dan menetapkannya ke kolom pkcs12
dari resource
smimeInfo
:
Java
Python
Mengupload sertifikat S/MIME
Untuk mengupload sertifikat, panggil
smimeInfo.insert
,
dan berikan resource smimeInfo
dalam isi permintaan:
Java
Python
Contoh untuk mengelola sertifikat banyak pengguna
Anda mungkin ingin mengelola sertifikat untuk banyak pengguna di organisasi sekaligus. Contoh berikut menunjukkan cara mengelola sertifikat untuk beberapa pengguna dalam satu panggilan batch.
Memasukkan sertifikat dari file CSV
Misalnya, Anda memiliki file CSV yang mencantumkan ID pengguna dan jalur ke sertifikat setiap pengguna:
$ 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
Anda dapat menggunakan panggilan createSmimeInfo
dan insertSmimeInfo
dari sebelumnya untuk mengupload sertifikat seperti yang ditentukan dalam file CSV:
Python
Anda dapat menggunakan panggilan create_smime_info
dan insert_smime_info
dari sebelumnya untuk mengupload sertifikat seperti yang ditentukan dalam file CSV:
Pengelolaan sertifikat
Contoh ini menggabungkan beberapa panggilan dari smimeInfo
API untuk menunjukkan cara Anda
dapat mengelola sertifikat untuk organisasi Anda. API ini mencantumkan sertifikat untuk pengguna dan jika sertifikat default telah habis masa berlakunya atau tidak disetel, API ini akan mengupload sertifikat yang ditemukan dalam file yang ditentukan. Kemudian, sertifikat yang masa berlakunya paling lama akan ditetapkan sebagai sertifikat default.
Kemudian, fungsi ini dipanggil dari fungsi yang memproses file CSV seperti pada contoh sebelumnya.