Gmail S/MIME API 提供程序化访问权限,以便为网域中的用户管理 S/MIME 电子邮件证书。 Google Workspace
管理员必须为网域启用 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 依赖于与 Gmail sendAs 方法相同的 ACL 范围:
- gmail.settings.basic
- 更新主 SendAs S/MIME 时,必须使用此范围。
- gmail.settings.sharing
- 如要更新自定义 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,该 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
- 要检索其密钥的别名。对于使用此别名发送的邮件,该地址会显示在邮件的“发件人:”标头中。
- id
- SmimeInfo 的不可变 ID。
为别名设置默认 S/MIME 密钥
使用 smimeInfo.setDefault() 方法将指定的 S/MIME 密钥标记为指定别名的默认密钥。 您可以使用以下参数标识目标别名:
- userId
- 用户的电子邮件地址。您可以使用特殊值
me
来指示当前经过身份验证的用户。 - sendAsEmail
- 要检索其密钥的别名。对于使用此别名发送的邮件,该地址会显示在邮件的“发件人:”标头中。
- id
- SmimeInfo 的不可变 ID。
示例代码
以下代码示例演示了如何使用 API 为拥有多用户的组织的 S/MIME 证书。
为 S/MIME 证书创建 SmimeInfo 资源
以下代码示例演示了如何从文件中读取证书、编码为 base64url 字符串,以及将其分配给 smimeInfo
资源的 pkcs12
字段:
Java
Python
上传 S/MIME 证书
如需上传证书,请调用 smimeInfo.insert
,并在请求正文中提供 smimeInfo
资源:
Java
Python
管理多个用户证书的示例
您可能希望一次为组织中的许多用户管理证书。 以下示例展示了如何通过一次批量调用管理多个用户的证书。
从 CSV 文件插入证书
假设您有一个 CSV 文件,其中列出了用户 ID 和每个用户证书的路径:
$ 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 文件的函数调用此方法,如上例所示。