Gmail S/MIME API, bir alandaki kullanıcılar için S/MIME e-posta sertifikalarını yönetmek üzere programatik erişim Google Workspace sağlar.
Sertifikaların çalışması için bir yöneticinin alanda S/MIME'yi etkinleştirmesi gerekir.
S/MIME standardı, ortak anahtar şifrelemesi ve MIME verilerinin imzalanması için bir spesifikasyon sağlar. Bir kullanıcı 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 postaları doğrulamak için gönderenin sertifikasını ve ortak anahtarını kullanır.
Ayrı S/MIME sertifikaları oluşturur ve bunları API'yi kullanarak yüklersiniz. Her S/MIME sertifikası, bir kullanıcı e-posta hesabının belirli bir takma adı içindir. Takma adlar, birincil e-posta adresinin yanı sıra özel "Farklı Gönder" adreslerini de içerir. Her takma ad için tek bir S/MIME sertifikası varsayılan olarak işaretlenir.
API erişimini yetkilendirme
API'ye erişimi yetkilendirmenin iki biçimi vardır:
- Alan genelinde yetki verilmiş bir hizmet hesabı kullanabilirsiniz. Bu terimlerin açıklaması için Kimlik doğrulama ve yetkilendirmeye genel bakış şartları bölümüne bakın. Bu seçeneğin etkinleştirilmesi hakkında bilgi edinmek için Alan genelinde yetki yetkisi ile hizmet hesabı oluşturma bölümünü 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ış bölümüne bakın. 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ı EKL kapsamlarına dayanır:
- gmail.settings.basic
- Bu kapsam, birincil SendAs S/MIME'nin güncellenmesi için gereklidir.
- gmail.settings.sharing
- Bu kapsam, gönderen S/MIME'den özel güncelleme yapmak için gereklidir.
API'yi kullanın
users.settings.sendAs.smimeInfo kaynağında S/MIME sertifikalarını yönetmek için kullandığınız yöntemler sunulur. Her sertifika, bir kullanıcı için tek bir farklı gönderme takma adıyla ilişkilendirilir.
S/MIME anahtarı yükle
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ı, 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 adres, bu takma ad kullanılarak gönderilen postalar için "From:" üstbilgisinde görünen e-posta adresidir.
S/MIME sertifikası ve özel anahtar, pkcs12
alanında bu biçimde olmalı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, kabul etmeden önce bu alanda standart doğrulamalar gerçekleştirir ve aşağıdakileri doğrular:
- Konu, belirtilen e-posta adresiyle eşleşiyor.
- Son kullanma tarihleri geçerli.
- Sertifikayı veren sertifika yetkilisi (CA), güvenilir kişiler listemizdedir.
- Sertifikalar, Gmail'in teknik kısıtlamalarıyla eşleşir.
Anahtar şifrelenmişse şifre, encryptedKeyPassword
alanında olmalıdır. Başarılı insert() çağrıları, gelecekte anahtara başvurmak için kullanılabilecek smimeInfo kimliğini döndürür.
Bir kullanıcının S/MIME anahtarlarını listeleme
Belirli bir takma ad için belirtilen kullanıcının S/MIME anahtarlarının listesini döndürmek için smimeInfo.list() yöntemini kullanın. Hedef takma adı, 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 adres, bu takma ad kullanılarak gönderilen postalar için "From:" üstbilgisinde görünen e-posta adresidir.
Bir takma adın S/MIME anahtarlarını alma
Bir kullanıcı için belirli bir gönderme takma adına ait belirli S/MIME anahtarlarını döndürmek için smimeInfo.get() yöntemini kullanın. Hedef takma adı, 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 adres, bu takma ad kullanılarak gönderilen postalar için "From:" ü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ı, 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 adres, bu takma ad kullanılarak gönderilen postalar için "Gönderen:" üstbilgisinde görünen e-posta adresidir.
- id
- SmimeInfo için sabit kimliktir.
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 için smimeInfo.setDefault() yöntemini kullanın. Hedef takma adı, 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 adres, bu takma ad kullanılarak gönderilen postalar için "Gönderen:" üstbilgisinde görünen e-posta adresidir.
- id
- SmimeInfo için sabit kimliktir.
Ö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 kullanımını göstermektedir.
S/MIME sertifikası için SmimeInfo kaynağı oluşturma
Aşağıdaki kod örneği, dosyadan sertifika okumayı, base64url dizesine kodlamayı ve bunu smimeInfo
kaynağının pkcs12
alanına atamayı göstermektedir:
Java
Python
S/MIME sertifikası yükleme
Sertifika yüklemek için smimeInfo.insert
çağrısı yapın ve isteğin gövdesinde smimeInfo
kaynağını sağlayın:
Java
Python
Çok sayıda kullanıcının sertifikasını yönetmeye ilişkin örnekler
Kuruluştaki birçok kullanıcının sertifikalarını aynı anda yönetmek isteyebilirsiniz. Aşağıdaki örnekler, tek bir toplu çağrıda birden çok kullanıcı için sertifikaların nasıl yönetileceğini gösterir.
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 önceki createSmimeInfo
ve insertSmimeInfo
çağrılarını kullanabilirsiniz:
Python
Sertifikaları CSV dosyasında belirtildiği şekilde yüklemek için önceki create_smime_info
ve insert_smime_info
çağrılarını kullanabilirsiniz:
Sertifika yönetimi
Bu örnekte, kuruluşunuz için sertifikaları nasıl yönetebileceğinizi göstermek için smimeInfo
API'den gelen çeşitli çağrılar birleştirilmektedir. Kullanıcının sertifikaları listeler. Varsayılan sertifikanın süresi dolmuş veya ayarlanmamışsa belirtilen dosyada bulunan sertifika yüklenir. Ardından, geçerlilik bitiş tarihi en uzak olan sertifikayı varsayılan olarak ayarlar.
Bu işlev, önceki örnekte olduğu gibi CSV dosyasını işleyen bir fonksiyondan çağrılır.