Gmail S/MIME API, bir Google Workspace alanındaki kullanıcılar için S/MIME e-posta sertifikalarını yönetmeye yönelik programatik erişim sağlar.
Sertifikaların çalışabilmesi için bir yöneticinin alan için S/MIME'yi etkinleştirmesi gerekir.
S/MIME standardı, MIME verilerinin ortak anahtarla şifrelenmesi ve imzalanması için bir spesifikasyon sağlar. Kullanıcının hesabında S/MIME sertifikalarının yapılandırılması, Gmail'in bu sertifikayı aşağıdaki şekillerde kullanmasına neden olur:
- Gmail, giden postaları imzalamak için kullanıcının sertifikasını ve özel anahtarını kullanır.
- Gmail, gelen postaların şifresini çözmek için kullanıcının özel anahtarını kullanır.
- Gmail, giden postaları şifrelemek için alıcının sertifikasını ve ortak anahtarını kullanır.
- Gmail, gelen postayı doğrulamak için gönderenin sertifikasını ve herkese açık anahtarını kullanır.
Her kullanıcı için ayrı S/MIME sertifikaları oluşturur ve bunları API'yi kullanarak yüklersiniz. Her S/MIME sertifikası, kullanıcı e-posta hesabının belirli bir takma adı içindir. Takma adlar, birincil e-posta adresinin yanı sıra özel "Şu Adresten Gönder" adreslerini içerir. Her takma ad için varsayılan olarak tek bir S/MIME sertifikası işaretlenir.
API erişimini yetkilendirme
API'ye erişim yetkisi verme işleminin iki yolu vardır:
- Alan genelinde yetki verme özelliğine sahip bir hizmet hesabı kullanabilirsiniz. Bu terimlerin açıklaması için Kimlik doğrulama ve yetkilendirmeye genel bakış terimleri başlıklı makaleyi inceleyin. Bu seçeneği etkinleştirme hakkında bilgi edinmek için Alan genelinde yetki verme özelliğine sahip bir hizmet hesabı oluşturma başlıklı makaleyi inceleyin.
- Oauth2 erişim jetonu almak için son kullanıcının iznini gerektiren standart bir OAuth2 akışı kullanabilirsiniz. Daha fazla bilgi için Kimlik doğrulama ve yetkilendirmeye genel bakış başlıklı makaleyi inceleyin. Bu seçeneği kullanmak için alan yöneticisinin, alan kontrol panelinde "S/MIME API son kullanıcı erişimi etkin" onay kutusunu etkinleştirmesi gerekir.
EKL kapsamları
Bu API, Gmail sendAs yöntemleriyle aynı ACL kapsamlarını kullanır:
- gmail.settings.basic
- Bu kapsam, birincil Gönderen Adı S/MIME'sini güncellemek için gereklidir.
- gmail.settings.sharing
- Bu kapsam, özel S/MIME'yi geliştirmek için gereklidir.
API'yi kullanma
users.settings.sendAs.smimeInfo kaynağı, S/MIME sertifikalarını yönetmek için kullandığınız yöntemleri sağlar. Her sertifika, bir kullanıcı için bir gönderen adı takma adıyla ilişkilendirilir.
S/MIME anahtarı yükleme
Bir kullanıcıya ait takma ad için yeni bir S/MIME anahtarı yüklemek üzere smimeInfo.insert() yöntemini kullanın. Hedef takma adını aşağıdaki parametreleri kullanarak tanımlarsınız:
- userId
- Kullanıcının e-posta adresi. Şu anda kimliği doğrulanmış kullanıcıyı belirtmek için
me
özel değerini kullanabilirsiniz. - sendAsEmail
- Anahtarı yüklediğiniz takma ad. Bu, bu takma ad kullanılarak gönderilen postaların "Gönderen:" üstbilgisinde görünen e-posta adresidir.
S/MIME sertifikası ve özel anahtar, pkcs12
alanında bu biçimde bulunmalıdır. İstekte başka alan ayarlanmamalıdır. PKCS12 alanının hem kullanıcı S/MIME anahtarını hem de imzalama sertifikası zincirini içermesi beklenir. API, bu alanı kabul etmeden önce standart doğrulamalar gerçekleştirerek aşağıdakileri doğrular:
- Konu, belirtilen e-posta adresiyle eşleşiyor.
- Son kullanma tarihleri geçerli olmalıdır.
- Sertifikayı veren sertifika yetkilisi (CA), güvenilir listemizde yer alıyor.
- Sertifikalar Gmail'in teknik kısıtlamalarıyla eşleşiyor.
Anahtar şifrelenmişse şifre encryptedKeyPassword
alanında olmalıdır. Başarılı insert() çağrıları, gelecekte anahtarı belirtmek için kullanılabilecek smimeInfo kimliğini döndürür.
Kullanıcının S/MIME anahtarlarını listeleme
Belirli bir kullanıcının, belirli bir takma ad için S/MIME anahtarlarının listesini döndürmek üzere smimeInfo.list() yöntemini kullanın. Hedef takma adını aşağıdaki parametreleri kullanarak tanımlarsınız:
- userId
- Kullanıcının e-posta adresi. Şu anda kimliği doğrulanmış kullanıcıyı belirtmek için
me
özel değerini kullanabilirsiniz. - sendAsEmail
- Anahtarların listeleneceği takma ad. Bu, bu takma ad kullanılarak gönderilen postaların "Gönderen:" üstbilgisinde görünen e-posta adresidir.
Takma ad için S/MIME anahtarlarını alma
Bir kullanıcının belirli bir gönderen adı için belirli S/MIME anahtarlarını döndürmek üzere smimeInfo.get() yöntemini kullanın. Hedef takma adını aşağıdaki parametreleri kullanarak tanımlarsınız:
- userId
- Kullanıcının e-posta adresi. Şu anda kimliği doğrulanmış kullanıcıyı belirtmek için
me
özel değerini kullanabilirsiniz. - sendAsEmail
- Anahtarları aldığınız takma ad. Bu, bu takma ad kullanılarak gönderilen postaların "Gönderen:" üstbilgisinde görünen e-posta adresidir.
S/MIME anahtarını silme
Belirtilen S/MIME anahtarını bir takma addan silmek için smimeInfo.delete() yöntemini kullanın. Hedef takma adını aşağıdaki parametreleri kullanarak tanımlarsınız:
- userId
- Kullanıcının e-posta adresi. Şu anda kimliği doğrulanmış kullanıcıyı belirtmek için
me
özel değerini kullanabilirsiniz. - sendAsEmail
- Anahtarları aldığınız takma ad. Bu, bu takma ad kullanılarak gönderilen postaların "Gönderen:" üstbilgisinde görünen e-posta adresidir.
- id
- SmimeInfo için sabit kimlik.
Takma ad için varsayılan S/MIME anahtarını ayarlama
Belirtilen S/MIME anahtarını, belirtilen takma ad için varsayılan olarak işaretlemek üzere smimeInfo.setDefault() yöntemini kullanın. Hedef takma adını aşağıdaki parametreleri kullanarak tanımlarsınız:
- userId
- Kullanıcının e-posta adresi. Şu anda kimliği doğrulanmış kullanıcıyı belirtmek için
me
özel değerini kullanabilirsiniz. - sendAsEmail
- Anahtarları aldığınız takma ad. Bu, bu takma ad kullanılarak gönderilen postaların "Gönderen:" üstbilgisinde görünen e-posta adresidir.
- id
- SmimeInfo için sabit kimlik.
Örnek kod
Aşağıdaki kod örnekleri, birden fazla kullanıcısı olan bir kuruluşun S/MIME sertifikalarını yönetmek için API'nin nasıl kullanıldığını gösterir.
S/MIME sertifikası için SmimeInfo kaynağı oluşturma
Aşağıdaki kod örneğinde, bir sertifikanın dosyadan okunması, base64url dizesi olarak kodlanması ve smimeInfo
kaynağının pkcs12
alanına atanması gösterilmektedir:
Java
Python
S/MIME sertifikası yükleme
Sertifika yüklemek için smimeInfo.insert
işlevini çağırın ve istek gövdesinde smimeInfo
kaynağını sağlayın:
Java
Python
Birçok kullanıcının sertifikasını yönetme örnekleri
Kuruluştaki birçok kullanıcının sertifikalarını tek seferde yönetmek isteyebilirsiniz. Aşağıdaki örneklerde, tek bir toplu çağrıda birden fazla kullanıcının sertifikalarının nasıl yönetileceği gösterilmektedir.
CSV dosyasından sertifika ekleme
Kullanıcı kimliklerini ve her kullanıcının sertifikasının yolunu listeleyen bir CSV dosyanız olduğunu varsayalım:
$ 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
Sertifikaları CSV dosyasında belirtildiği şekilde yüklemek için daha önceki createSmimeInfo
ve insertSmimeInfo
çağrılarını kullanabilirsiniz:
Python
Sertifikaları CSV dosyasında belirtildiği şekilde yüklemek için daha önceki create_smime_info
ve insert_smime_info
çağrılarını kullanabilirsiniz:
Sertifika yönetimi
Bu örnekte, kuruluşunuzun sertifikalarını nasıl yönetebileceğinizi göstermek için smimeInfo
API'sinden alınan çeşitli çağrılar birleştirilmiştir. Kullanıcının sertifikalarını listeler ve varsayılan sertifikanın süresi dolmuşsa veya ayarlanmamışsa belirtilen dosyada bulunan sertifikayı yükler. Ardından, geçerlilik süresi en uzun olan sertifikayı varsayılan olarak ayarlar.
Daha sonra bu işlev, önceki örnekte olduğu gibi bir CSV dosyasını işleyen bir işlevden çağrılır.