S/MIME API Gmail menyediakan akses terprogram untuk mengelola sertifikat email S/MIME bagi pengguna di Google Workspace domain.
Administrator harus mengaktifkan S/MIME untuk domain agar sertifikat dapat berfungsi.
Standar S/MIME menyediakan 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 dapat membuat sertifikat S/MIME satu per satu dan menguploadnya menggunakan API. Setiap sertifikat S/MIME ditujukan untuk alias tertentu bagi akun email pengguna. Alias mencakup alamat email utama serta alamat khusus "Kirim Sebagai". 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 otoritas tingkat domain. Untuk mendapatkan penjelasan tentang persyaratan ini, baca Persyaratan ringkasan autentikasi dan otorisasi. Untuk mengetahui informasi tentang cara mengaktifkan opsi ini, lihat Membuat akun layanan dengan pendelegasian otoritas 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 mengaktifkan kotak centang "Akses pengguna akhir S/MIME API diaktifkan" di panel kontrol Domain.
Cakupan ACL
API ini bergantung pada cakupan ACL yang sama dengan metode Gmail sendAs:
- gmail.settings.basic
- Cakupan ini diperlukan untuk memperbarui S/MIME SendAs utama.
- gmail.settings.sharing
- Cakupan ini diperlukan untuk memperbarui setelan kustom dari S/MIME.
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.
Upload 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 yang Anda upload 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; kolom lain tidak harus ditetapkan
dalam permintaan. Kolom PKCS12 diharapkan berisi kunci S/MIME pengguna
dan rantai sertifikat penandatanganan. API melakukan validasi standar pada kolom ini
sebelum menerimanya, memverifikasi hal berikut:
- Subjek cocok dengan alamat email yang ditentukan.
- Waktu habis valid.
- Certificate authority (CA) penerbit tercantum dalam daftar tepercaya kami.
- Sertifikat cocok dengan batasan teknis Gmail.
Jika kunci dienkripsi, sandi harus berada di kolom
encryptedKeyPassword
. Panggilan insert() yang berhasil akan menampilkan ID smimeInfo yang dapat digunakan untuk merujuk ke kunci di masa mendatang.
Mencantumkan kunci S/MIME pengguna
Gunakan metode smimeInfo.list() untuk menampilkan daftar kunci S/MIME bagi pengguna yang ditentukan untuk alias yang diberikan. 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 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 saat Anda mengambil kuncinya. Ini adalah alamat email yang muncul di header "Dari:" untuk email yang dikirim menggunakan alias ini.
Menghapus kunci S/MIME
Menggunakan metode smimeInfo.delete() untuk menghapus kunci S/MIME yang ditentukan 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 saat Anda mengambil kuncinya. 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 yang ditentukan sebagai default untuk alias yang ditentukan. 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 saat Anda mengambil kuncinya. 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 untuk organisasi dengan beberapa pengguna.
Membuat resource SmimeInfo untuk sertifikat S/MIME
Contoh kode berikut menunjukkan pembacaan sertifikat dari file, encoding
ke string base64url, dan menetapkannya ke kolom pkcs12
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.
Menyisipkan sertifikat dari file CSV
Misalkan Anda memiliki file CSV yang mencantumkan ID pengguna dan jalur ke setiap sertifikat 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
mengelola sertifikat untuk organisasi Anda. Layanan ini mencantumkan sertifikat untuk
pengguna dan jika sertifikat default telah habis masa berlakunya atau tidak disetel, sertifikat yang ditemukan dalam
file yang ditentukan akan diupload. Kemudian, kode tersebut akan menetapkan sertifikat yang masa berlakunya paling jauh
di masa mendatang sebagai default.
Selanjutnya, fungsi ini akan dipanggil dari fungsi yang memproses file CSV seperti pada contoh sebelumnya.