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 証明書は、ユーザーのメール アカウントの特定のエイリアス用です。エイリアスには、メインのメールアドレスとカスタムの「名前」アドレスが含まれます。エイリアスごとに 1 つの S/MIME 証明書がデフォルトとしてマークされます。
API アクセスの承認
API へのアクセスを承認する方法は 2 つあります。
- ドメイン全体の権限委任のあるサービス アカウントを使用できます。これらの用語の説明については、認証と認可の概要の用語をご覧ください。このオプションを有効にする方法については、ドメイン全体の権限委任を使用してサービス アカウントを作成するをご覧ください。
- エンドユーザーの同意を必要とする標準の OAuth2 フローを使用して、Oauth2 アクセス トークンを取得できます。詳細については、認証と認可の概要をご覧ください。このオプションを使用するには、ドメイン管理者がドメイン コントロール パネルで [S/MIME API エンドユーザー アクセスを有効にする] チェックボックスをオンにする必要があります。
ACL スコープ
この API は、Gmail sendAs メソッドと同じ ACL スコープに依存します。
- gmail.settings.basic
- このスコープは、プライマリ SendAs S/MIME を更新するために必要です。
- gmail.settings.sharing
- このスコープは、カスタム from S/MIME を更新するために必要です。
API の使用
users.settings.sendAs.smimeInfo リソースは、S/MIME 証明書の管理に使用するメソッドを提供します。各証明書は、ユーザーの 1 つの「差出人」エイリアスに関連付けられています。
S/MIME 鍵をアップロードする
smimeInfo.insert() メソッドを使用して、ユーザーに属するエイリアスの新しい S/MIME 鍵をアップロードします。ターゲット エイリアスは、次のパラメータを使用して識別します。
- userId
- ユーザーのメールアドレス。特別な値
me
を使用して、現在認証されているユーザーを示すことができます。 - sendAsEmail
- 鍵をアップロードするエイリアス。このエイリアスを使用して送信されたメールの [From:] ヘッダーに表示されるメールアドレスです。
S/MIME 証明書と秘密鍵は、その形式で pkcs12
フィールドに存在している必要があります。リクエストで他のフィールドを設定することはできません。PKCS12 フィールドには、ユーザーの S/MIME 鍵と署名証明書チェーンの両方が含まれている必要があります。API は、このフィールドを受け入れる前に標準の検証を行い、次のことを確認します。
- 件名が指定されたメールアドレスと一致します。
- 有効期限は有効です。
- 発行元の認証局(CA)が信頼できるリストに含まれている。
- 証明書が Gmail の技術的な制約を満たしている。
鍵が暗号化されている場合、パスワードは encryptedKeyPassword
フィールドに指定する必要があります。insert() 呼び出しが成功すると、smimeInfo の ID が返されます。この ID は、今後キーを参照するために使用できます。
ユーザーの S/MIME 鍵のリストを取得する
smimeInfo.list() メソッドを使用して、指定されたユーザーの指定されたエイリアスの S/MIME 鍵のリストを返します。ターゲット エイリアスは、次のパラメータを使用して識別します。
- userId
- ユーザーのメールアドレス。特別な値
me
を使用して、現在認証されているユーザーを示すことができます。 - sendAsEmail
- 鍵を一覧表示するエイリアス。このエイリアスを使用して送信されたメールの [From:] ヘッダーに表示されるメールアドレスです。
エイリアスの S/MIME 鍵を取得する
smimeInfo.get() メソッドを使用して、ユーザーの特定の送信専用エイリアスの特定の S/MIME 鍵を返します。ターゲット エイリアスは、次のパラメータを使用して識別します。
- userId
- ユーザーのメールアドレス。特別な値
me
を使用して、現在認証されているユーザーを示すことができます。 - sendAsEmail
- 鍵を取得するエイリアス。このエイリアスを使用して送信されたメールの [From:] ヘッダーに表示されるメールアドレスです。
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 を使用して複数のユーザーがいる組織の S/MIME 証明書を管理する方法を示しています。
S/MIME 証明書の SmimeInfo リソースを作成する
次のコード例は、ファイルから証明書を読み取り、base64url 文字列にエンコードして、smimeInfo
リソースの pkcs12
フィールドに割り当てる方法を示しています。
Java
Python
S/MIME 証明書をアップロードする
証明書をアップロードするには、smimeInfo.insert
を呼び出し、リクエストの本文で smimeInfo
リソースを指定します。
Java
Python
多くのユーザーの証明書を管理する例
組織内の多くのユーザーの証明書を一度に管理したい場合があります。次の例は、1 回のバッチ呼び出しで複数のユーザーの証明書を管理する方法を示しています。
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 ファイルを処理する関数から呼び出されます。