Apigee ルート CA 証明書とローテーションについて

このページの内容は Apigee に適用されます。Apigee ハイブリッドには適用されません。

Apigee Edge のドキュメントを表示する

このページでは、Apigee ランタイムへの TLS 接続を保護する Apigee ルート認証局（CA）証明書について説明し、ローテーション プロセスについて説明します。また、ローテーションの影響を受けるアクセス パターンと、アプリケーションを準備するために必要な手順も一覧表示されます。

スナップショット: クライアントが Apigee ランタイムに直接接続する場合（内部ルーティング TLS オプション 2 または直接 TCP 接続を使用する場合など）にのみ、アクションが必要です。トラフィックが TLS を終端する顧客管理の外部または内部ロードバランサを通過する場合は、対応は不要です。

ルート CA 証明書について

各 Apigee 組織には、TLS 終端用に Apigee ランタイム Ingress で使用されるサーバー証明書を発行する Google マネージド ルート CA 証明書があります。クライアントが Apigee インスタンスへの HTTPS 接続を開くと、サーバーはこのルート CA にチェーンする証明書を提示します。サーバー証明書を検証するクライアントは、ルート CA を暗黙的（TLS を終了する顧客管理のロードバランサを介してトラフィックが流れる場合）または明示的（クライアントが Apigee ランタイムに直接接続する場合）に信頼する必要があります。

ルート CA 証明書は、caCertificates[] フィールドの organizations.get API レスポンスで公開されます。このフィールドは配列です。ローテーション中に、現在のルート CA 証明書と今後のルート CA 証明書の両方が同時に返されるため、クライアントは切り替え前に両方を信頼できます。

注: 非推奨の caCertificate（単数形）フィールドは、1 つの証明書のみを返し、ローテーション中に次の証明書を表示しません。caCertificate を読み取るツールを、代わりに caCertificates[] を読み取るように更新します。

ルート CA 証明書がローテーションされる理由

Apigee ルート CA 証明書には、長いが有限の有効期間（通常は 10 年）があります。有効期限が切れる前にローテーションされるため、次のようになります。

• Apigee ランタイムを保護する証明書は、使用中は期限切れになりません。
• Apigee コンポーネント間の内部通信チャネルは、中断することなく動作し続けます。

ローテーションは、計画されたルーチン オペレーションです。Apigee は、 Google Cloud が制御するスケジュールで実行します。ローテーションは開始されず、ローテーション自体によって Apigee ランタイム エンドポイントまたは Apigee API サーフェスが変更されることもありません。

ローテーションのステージとタイムライン

Apigee は、4 つの段階でルート CA 証明書をローテーションします。各ステージは段階的です。組織全体にリージョンごとに適用され、完了までに時間がかかります。次の表に、各ステージのユーザーに影響する内容と、現在のルート CA の有効期限を基準とした一般的な開始時期を示します。

ステージ	一般的なタイミング	caCertificates[] の内容	影響
1. 新しい証明書が公開されました	現在の証明書の有効期限が切れる約 1 年前	現在と新規（両方）	Apigee は新しいルート CA 証明書を生成し、Apigee 所有のすべてのコンポーネントのトラストストアに追加します。新しい証明書は organizations.get レスポンスにも表示されるため、取得してステージングできます。Apigee ランタイムは、現在のルート CA によって署名されたサーバー証明書を引き続き提示するため、既存のクライアントはまだ影響を受けません。このステージが開始すると、Apigee はお客様に通知を送信します。
2. リーフ証明書の切り替え	現在の証明書の有効期限の約 60 日前	現在と新規（両方）	Apigee ランタイムは、新しいルート CA によって署名された新しいサーバー（リーフ）証明書の提示を開始します。現在のルート CA のみを信頼するクライアントは、このステージがリージョンで完了すると、TLS 検証に失敗します。両方の証明書（または新しい証明書のみ）を信頼するクライアントは引き続き動作します。このステージが開始されると、Apigee はお客様に通知を送信します。
3. 古い証明書が取り消されました	現在の証明書の有効期限の約 30 日前	新品のみ	Apigee は、内部トラストストアから古いルート CA を削除し、organizations.get からの返信を停止します。古いルート CA のみを信頼しているクライアントは接続できません。このステージが開始すると、Apigee はお客様に通知を送信します。
4. ローテーションが完了しました	元の有効期限	新品のみ	Apigee は古いルート CA を完全に削除し、ローテーションが完了します。新しいルート CA が唯一のルート CA となり、新しい約 10 年のサイクルが始まります。このステージが完了すると、Apigee はお客様に通知を送信します。

注: 各ステージでは、組織内のすべてのインスタンスとリージョンにロールアウトするまでに時間がかかります（通常、インスタンスごとに数分から数時間）。段階的ロールアウト中、その組織のインスタンス管理オペレーションは一時停止されます。

ローテーションの影響を受けるユーザー

ローテーションで対応が必要かどうかは、クライアントが Apigee ランタイムにアクセスする方法によって異なります。

アクセス パターン	対応が必要ですか？	理由
Google Cloud 外部アプリケーション ロードバランサを使用した外部ルーティング（MIG）	×	外部ロードバランサは、ユーザーが管理する証明書を使用して TLS を終端します。クライアントは Apigee ルート CA ではなく、証明書を信頼します。ローテーションはこれらのクライアントには影響しません。
内部ルーティング（VPC）、TLS オプション 1（内部 HTTPS アプリケーション ロードバランサ）	×	内部ロードバランサは、ユーザーが管理する証明書を使用して TLS を終端します。クライアントは Apigee ルート CA ではなく、証明書を信頼します。ローテーションはこれらのクライアントには影響しません。
内部ルーティング（VPC）、TLS オプション 2（内部デフォルトの完全修飾ドメイン名）	○	クライアントは Apigee 管理の内部ロードバランサに直接接続し、Apigee 発行のサーバー証明書を検証します。ローテーションのカットオーバーの前に、各クライアントが新しいルート CA を信頼する必要があります。
ランタイム インスタンスの上り（内向き）IP への直接 TCP 接続（内部 TCP ロードバランサ経由など）	○	クライアントは Apigee が発行したサーバー証明書を検証します。ローテーションのカットオーバーの前に、各クライアントが新しいルート CA を信頼する必要があります。
TLS を使わないオプション（curl -k フラグ、または証明書の検証をスキップするクライアント）	×	クライアントはサーバー証明書を検証しないため、ローテーションは機能に影響しません。このオプションは、テスト環境以外ではおすすめしません。

注意: アプリケーションが Apigee ルート CA を OS トラストストア、アプリケーション管理のトラストストア、サイドカー、サービス メッシュ トラスト バンドルに保存している場合は、ローテーション カットオーバーの前に、新しいルート CA をそのようなトラストストアすべてに追加する必要があります。そうしないと、カットオーバー後に TLS ハンドシェイクが失敗し、クライアントに x509: certificate signed by unknown authority や SSL_ERROR_BAD_CERT_DOMAIN などのエラーが表示されます。

ローテーションの準備方法

アクションが必要なアクセス パターンのいずれかを使用している場合は、ローテーション通知で受け取ったローテーションのカットオーバー日までに、次の手順を行います。

前提条件: 次のコマンドラインの例では、システムに curl、jq、awk、base64、openssl ユーティリティがインストールされている必要があります。

ステップ 1: Apigee ランタイム インスタンスを検出する

組織内の Apigee ランタイム インスタンスを一覧表示します。各インスタンスには専用の下り（内向き）IP があります。これは、直接接続クライアントが到達するホストです。

# Ensure $AUTH and $PROJECT_ID are set in your environment
curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \
  | jq -r '.instances[] | "\(.name)\t\(.host)"'

クライアントがこれらの IP 以外のホスト（内部ロードバランサの前の独自の DNS 名など）に接続する場合は、代わりにそのホストを使用します。

ステップ 2: 現在と今後のルート CA 証明書を取得する

organizations.get から caCertificates[] フィールドを読み取ります。ローテーション中、この配列には現在のルート CA と新しいルート CA の両方が含まれます。それぞれ base64 でエンコードされています。

curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

各エントリを PEM 形式にデコードし、有効期間を調べて新しい証明書を特定します。

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
  echo "==> ${f%.b64}.crt"
  openssl x509 -in "${f%.b64}.crt" -noout -subject -issuer -dates
done

notAfter の日付が新しい証明書が新しいルート CA です。

ステップ 3: 新しいルート CA をトラストストアに追加する

現在 Apigee ルート CA を信頼しているすべてのクライアント トラストストアに、新しいルート CA 証明書を追加します。カットオーバーが完了するまで現在のルート CA をそのままにしておき、カットオーバー ウィンドウで接続が引き続き機能するようにします。切り替え後、トラストストアから古いルート CA を削除できます。

正確な手順はクライアントによって異なります。一般的なケースは次のとおりです。

• 証明書を OS レベルのトラストストアに追加する（Debian ベースのシステムで /etc/ssl/certs/ の後に update-ca-certificates を実行するなど）。
• アプリケーション管理のトラストストアに証明書を追加する（Java cacerts キーストア、Nginx ssl_trusted_certificate バンドル、Envoy validation_context トラスト バンドルなど）。
• ワークロード Pod にマウントされている Kubernetes Secret または ConfigMap に証明書を追加する。

ステップ 4: 新しいルート CA で接続が機能することを確認する

新しいルート CA をステージングしたら、新しい証明書のみを信頼した場合に Apigee ランタイムへの HTTPS リクエストが成功することを確認します。

# Ensure $ENV_GROUP_HOSTNAME and $INTERNAL_LOAD_BALANCER_IP are set
curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

このコマンドが成功すると、クライアントはカットオーバーの準備が整います。失敗した場合は、クライアントが新しいルート CA をまだ信頼していないため、ステップ 3 に戻ります。

例: 内部ルーティング（VPC）、TLS オプション 2

この例では、内部ルーティング（VPC）の TLS オプション 2 に記載されているアクセス パターンのローテーション手順を示します。このパターンでは、クライアントが Apigee 内部ロードバランサーに直接接続し、Apigee 自己署名証明書を検証します。これは、ローテーションの影響を最も受けやすいアクセス パターンです。

切り替え前:

1. Apigee 内部ロードバランサの IP を取得します。

   export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
     https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
     | jq -r '.instances[0].host')

2. 現在のルート CA と新しいルート CA を別々のファイルに取得し、新しいルート CA を特定します。

   curl -H "$AUTH" \
     https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
     | jq -r '.caCertificates[]' \
     | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'
   
   for f in ca_*.b64; do
     base64 -d "$f" > "${f%.b64}.crt"
   done
   
   # Identify the new root CA (latest notAfter):
   openssl x509 -in ca_1.crt -noout -dates
   openssl x509 -in ca_2.crt -noout -dates

3. 現在のルート CA と新しいルート CA の両方を含む結合トラストストアを構築し、テスト リクエストに使用します。

   cat ca_1.crt ca_2.crt > cacert-combined.crt
   
   curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
     https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
     --cacert cacert-combined.crt \
     --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

   このリクエストが成功したら、cacert-combined.crt をクライアントのトラストストアとしてデプロイします。結合されたトラストストアは、現在も現在の証明書を検証し、カットオーバー後に新しい証明書を検証します。

カットオーバー後（通常はカットオーバー日の数日以内）、新しい証明書のみを信頼したときに接続が成功することを確認して、ローテーションを確認します。

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

このリクエストが成功したら、トラストストアから古いルート CA を安全に削除できます。

通知

Apigee は、各ローテーション ステージの開始時に、 Google Cloud プロジェクトのプロジェクト オーナーと組織オーナーに通知を送信します。各通知には、ステージ名、ステージが組織に適用される日付、このページへのリンクが含まれています。

通知	お客様に推奨される対応
1. 新しい証明書が公開されました （有効期限の約 1 年前）	caCertificates[] から新しいルート CA を取得し、現在 Apigee ルート CA を信頼しているすべてのクライアント トラストストアに追加します。ローテーションの準備方法をご覧ください。
2. リーフ証明書の切り替え （有効期限の約 60 日前）	このステージがリージョンに適用される前に、すべてのクライアントが新しいルート CA を信頼していることを確認します。この段階を過ぎると、古いルート CA のみを信頼するクライアントは接続できなくなります。
3. 古い証明書が取り消されました （有効期限の約 30 日前）	このステージがすべてのリージョンに適用されたら、クライアントのトラストストアから古いルート CA を安全に削除できます。
4. ローテーション完了 （元の有効期限）	対応は不要です。古いルート CA は完全に削除され、新しいルート CA が組織の唯一のルート CA になっています。

ローテーション通知が届かず、ローテーションの影響を受けるユーザーに記載されているアクセス パターンのいずれかを使用している場合は、Apigee サポートにお問い合わせのうえ、組織の通知受信者を確認してください。

次のステップ

• TLS の構成オプションを確認して、Apigee のすべての TLS 終端オプションを理解します。
• 内部アクセス呼び出しパターンの完全なセットについては、内部専用アクセスで API プロキシを呼び出すをご覧ください。
• caCertificates[] フィールドの完全なスキーマについては、organizations.get API リファレンスをご覧ください。