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 証明書は、ユーザーのメール アカウントの特定のエイリアス用です。エイリアスには、メインのメールアドレスとカスタムの「差出人」アドレスが含まれます。 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
- このスコープは、カスタムの S/MIME から更新するために必要です。
API の使用
users.settings.sendAs.smimeInfo リソースは、S/MIME 証明書の管理に使用するメソッドを提供します。各証明書は、ユーザーの 1 つの送信元エイリアスに関連付けられます。
S/MIME キーをアップロードする
ユーザーのエイリアスの新しい S/MIME キーをアップロードするには、smimeInfo.insert() メソッドを使用します。ターゲット エイリアスは、次のパラメータを使用して指定します。
- userId
- ユーザーのメールアドレス。特別な値
me
を使用して、現在認証されているユーザーを示すことができます。 - sendAsEmail
- 鍵をアップロードするエイリアス。これは、このエイリアスを使用して送信されたメールの「From:」ヘッダーに表示されるメールアドレスです。
S/MIME 証明書と秘密鍵は、その形式で pkcs12
フィールドに存在する必要があります。他のフィールドはリクエストに含めないでください。PKCS12 フィールドには、ユーザーの S/MIME 鍵と署名証明書チェーンの両方が含まれている必要があります。API はこのフィールドを受け入れる前に標準検証を実行し、次のことを検証します。
- 件名が、指定したメールアドレスと一致する。
- 有効期限は有効です。
- 発行元の認証局(CA)が Google の信頼できるリストに登録されている。
- 証明書が Gmail の技術的な制約と一致している。
鍵が暗号化されている場合、パスワードは encryptedKeyPassword
フィールドに入力する必要があります。insert() の呼び出しが成功すると、smimeInfo の ID が返されます。この ID は、後でキーの参照に使用できます。
ユーザーの S/MIME キーを一覧表示する
指定されたエイリアスについて、指定されたユーザーの S/MIME キーのリストを返すには、smimeInfo.list() メソッドを使用します。ターゲット エイリアスは、次のパラメータを使用して指定します。
- 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 ファイルを処理する関数から呼び出されます。