Gmail S/MIME API 提供程式輔助存取權,讓您為 Google Workspace 網域中的使用者管理 S/MIME 電子郵件憑證。
管理員必須為網域啟用 S/MIME,憑證才能正常運作。
S/MIME 標準為公開金鑰加密及 MIME 資料簽署作業提供規範。在使用者帳戶中設定 S/MIME 憑證,促使 Gmail 以下列方式使用該憑證:
- Gmail 會使用使用者的憑證和私密金鑰簽署外寄郵件。
- Gmail 會使用使用者的私密金鑰解密收到的郵件。
- Gmail 會使用收件者的憑證和公開金鑰為外寄郵件加密。
- Gmail 會使用寄件者的憑證和公開金鑰驗證收到的郵件。
您必須產生個別 S/MIME 憑證,並使用 API 上傳這些憑證。每個 S/MIME 憑證都是使用者電子郵件帳戶的特定別名。別名包括主要電子郵件地址,以及自訂的「以這個地址寄送」地址。 系統會將單一 S/MIME 憑證標示為每個別名的預設值。
授權 API 存取權
授權存取 API 的方式有兩種:
- 您可以將服務帳戶與全網域授權委派搭配使用。如需這些術語的說明,請參閱驗證和授權總覽詞彙。如要進一步瞭解如何啟用這個選項,請參閱「建立具備全網域授權委派的服務帳戶」一節。
- 您可以使用標準 OAuth2 流程,要求使用者同意取得 Oauth2 存取權杖。詳情請參閱驗證與授權總覽。如要使用這個選項,網域管理員必須在網域控制台中啟用「已啟用 S/MIME API 使用者存取權」核取方塊。
ACL 範圍
這個 API 使用的 ACL 範圍與 Gmail sendAs 方法相同:
- gmail.settings.basic
- 這是更新主要 SendAs S/MIME 的必要範圍。
- gmail.settings.sharing
- 這是更新自訂「from」S/MIME 時的必要範圍。
使用 API
users.settings.sendAs.smimeInfo 資源提供了您用來管理 S/MIME 憑證的方法。每個憑證都會與使用者一個以「傳送」的別名建立關聯。
上傳 S/MIME 金鑰
使用 smimeInfo.insert() 方法為屬於使用者的別名上傳新的 S/MIME 金鑰。請使用下列參數來識別目標別名:
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me
來表示目前已驗證的使用者。 - sendAsEmail
- 要上傳金鑰的別名。透過這個別名傳送的郵件,在「寄件者:」標頭中會顯示這個電子郵件地址。
S/MIME 憑證和私密金鑰應以該格式出現在 pkcs12
欄位中;要求中不應設定其他欄位。PKCS12 欄位應同時包含使用者 S/MIME 金鑰和簽署憑證鏈結。API 會先對這個欄位執行標準驗證,然後再接受,並驗證以下內容:
- 主旨與指定的電子郵件地址相符。
- 到期後即失效。
- 憑證授權單位 (CA) 已列入信任清單。
- 憑證符合 Gmail 的技術限制。
如果金鑰已加密,密碼應在 encryptedKeyPassword
欄位中。成功的 insert() 呼叫將傳回 smimeInfo 的 ID,未來可用來參照金鑰。
列出使用者的 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
- 您要擷取金鑰的別名。使用這個別名傳送的郵件會在「From:」標頭中顯示的電子郵件地址。
- id
- SmimeInfo 的不可變更 ID。
為別名設定預設 S/MIME 金鑰
使用 smimeInfo.setDefault() 方法,將指定的 S/MIME 金鑰標示為指定別名的預設值。請使用下列參數來識別目標別名:
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me
來表示目前已驗證的使用者。 - sendAsEmail
- 您要擷取金鑰的別名。使用這個別名傳送的郵件會在「From:」標頭中顯示的電子郵件地址。
- id
- SmimeInfo 的不可變更 ID。
程式碼範例
下列程式碼範例示範如何使用 API 為有多位使用者的機構,使用 API 管理 S/MIME 憑證。
為 S/MIME 憑證建立 SmimeInfo 資源
下列程式碼範例示範如何從檔案讀取憑證、將憑證編碼為 base64url 字串,以及指派給 smimeInfo
資源的 pkcs12
欄位:
Java
Python
上傳 S/MIME 憑證
如要上傳憑證,請呼叫 smimeInfo.insert
,並在要求內文中提供 smimeInfo
資源:
Java
Python
管理多位使用者憑證的範例
建議您一次管理機構中多位使用者的憑證。以下範例說明如何透過單一批次呼叫,管理多位使用者的憑證。
從 CSV 檔案插入憑證
假設您有列出使用者 ID 和每位使用者憑證路徑的 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 檔案的函式呼叫此方法。