Tentang sertifikat CA root Apigee dan rotasi

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan sertifikat root certificate authority (CA) Apigee yang mengamankan koneksi TLS ke runtime Apigee, dan menjelaskan proses rotasi. Bagian ini juga mencantumkan pola akses yang terpengaruh oleh rotasi dan langkah-langkah yang harus Anda lakukan untuk menyiapkan aplikasi.

Tentang sertifikat CA root

Setiap organisasi Apigee memiliki sertifikat CA root yang dikelola Google yang menerbitkan sertifikat server yang digunakan oleh ingress runtime Apigee untuk TLS termination. Saat klien membuka koneksi HTTPS ke instance Apigee, server akan menampilkan sertifikat yang dirantai ke CA root ini. Klien yang memvalidasi sertifikat server harus memercayai CA root, baik secara implisit (saat traffic mengalir melalui load balancer yang dikelola pelanggan yang menghentikan TLS) maupun secara eksplisit (saat klien terhubung langsung ke runtime Apigee).

Sertifikat CA root ditampilkan dalam respons API organizations.get di kolom caCertificates[]. Kolom ini adalah array karena, selama rotasi, sertifikat CA root saat ini dan yang akan datang ditampilkan secara bersamaan sehingga klien dapat memercayai keduanya sebelum peralihan.

Alasan sertifikat CA root dirotasi

Sertifikat CA root Apigee memiliki periode validitas yang panjang tetapi terbatas (biasanya 10 tahun). Sertifikat dirotasi sebelum masa berlakunya habis sehingga:

  • Sertifikat yang mengamankan runtime Apigee tidak pernah berakhir saat digunakan.
  • Saluran komunikasi internal antar-komponen Apigee akan terus berfungsi tanpa gangguan.

Rotasi adalah operasi rutin yang direncanakan. Apigee menjalankannya sesuai jadwal yang Google Cloud dikontrol. Anda tidak memulai rotasi, dan rotasi itu sendiri tidak mengubah endpoint runtime Apigee atau antarmuka API Apigee.

Tahapan dan linimasa rotasi

Apigee mengganti sertifikat CA root dalam empat tahap. Setiap tahap dilakukan secara bertahap: diterapkan di setiap wilayah di seluruh organisasi Anda dan membutuhkan waktu untuk diselesaikan. Tabel di bawah menjelaskan efek yang terlihat oleh pelanggan dari setiap tahap dan waktu dimulainya yang umum, yang diukur relatif terhadap tanggal habis masa berlaku CA root saat ini.

Tahap Waktu umum Isi caCertificates[] Yang terjadi
1. Sertifikat baru dipublikasikan Sekitar 1 tahun sebelum masa berlaku sertifikat saat ini berakhir Saat ini dan baru (keduanya) Apigee membuat sertifikat CA root baru dan menambahkannya ke truststore setiap komponen milik Apigee. Sertifikat baru juga muncul dalam respons organizations.get sehingga Anda dapat mengambil dan menyajikannya. Runtime Apigee terus memberikan sertifikat server yang ditandatangani oleh CA root saat ini, sehingga klien yang ada belum terpengaruh. Apigee mengirimkan notifikasi pelanggan saat tahap ini dimulai.
2. Pengalihan sertifikat entitas akhir Sekitar 60 hari sebelum masa berlaku sertifikat saat ini berakhir Saat ini dan baru (keduanya) Runtime Apigee mulai menampilkan sertifikat server (leaf) baru yang ditandatangani oleh root CA baru. Klien yang hanya memercayai CA root saat ini akan gagal melakukan validasi TLS setelah tahap ini selesai di wilayahnya. Klien yang memercayai kedua sertifikat (atau hanya sertifikat baru) akan terus berfungsi. Apigee mengirimkan notifikasi pelanggan saat tahap ini dimulai.
3. Sertifikat lama dibatalkan Sekitar 30 hari sebelum masa berlaku sertifikat saat ini berakhir Khusus produk baru Apigee menghapus CA root lama dari truststore internal dan berhenti menampilkannya dari organizations.get. Klien yang masih memercayai hanya CA root lama tidak dapat terhubung. Apigee mengirimkan notifikasi pelanggan saat tahap ini dimulai.
4. Rotasi selesai Pada tanggal habis masa berlaku asli Khusus produk baru Apigee akan menghapus CA root lama secara permanen dan rotasi selesai. CA root baru kini menjadi satu-satunya CA root, dan siklus baru sekitar 10 tahun dimulai. Apigee mengirimkan notifikasi pelanggan saat tahap ini selesai.

Siapa yang terpengaruh oleh rotasi

Apakah rotasi memerlukan tindakan dari Anda bergantung pada cara klien menjangkau runtime Apigee Anda:

Pola akses Tindakan diperlukan? Mengapa
Perutean eksternal (MIG) dengan Load Balancer Aplikasi eksternal Google Cloud Tidak Load balancer eksternal Anda menghentikan TLS menggunakan sertifikat yang Anda kelola. Klien memercayai sertifikat Anda, bukan CA root Apigee. Rotasi tidak memengaruhi klien ini.
Perutean internal (VPC), Opsi TLS 1 (Load Balancer Aplikasi HTTPS internal) Tidak Load balancer internal Anda menghentikan TLS menggunakan sertifikat yang Anda kelola. Klien memercayai sertifikat Anda, bukan CA root Apigee. Rotasi tidak memengaruhi klien ini.
Perutean internal (VPC), Opsi TLS 2 (nama domain yang sepenuhnya memenuhi syarat default internal) Ya Klien terhubung langsung ke load balancer internal yang dikelola Apigee dan memvalidasi sertifikat server yang dikeluarkan Apigee. Setiap klien harus memercayai CA root baru sebelum pengalihan rotasi.
Koneksi TCP langsung ke IP ingress instance runtime (misalnya, melalui load balancer TCP internal) Ya Klien memvalidasi sertifikat server yang dikeluarkan Apigee. Setiap klien harus memercayai CA root baru sebelum peralihan berlangsung.
Opsi non-TLS (flag curl -k, atau klien apa pun yang melewati validasi sertifikat) Tidak Klien tidak memvalidasi sertifikat server, sehingga rotasi tidak memiliki efek fungsional. Opsi ini tidak direkomendasikan di luar lingkungan pengujian.

Cara mempersiapkan rotasi

Jika Anda menggunakan salah satu pola akses yang memerlukan tindakan, ikuti langkah-langkah ini sebelum tanggal peralihan rotasi yang Anda terima dalam notifikasi rotasi.

Langkah 1: Temukan instance runtime Apigee

Mencantumkan instance runtime Apigee di organisasi Anda. Setiap instance memiliki IP ingress khusus, yang merupakan host yang dijangkau oleh klien direct-connect.

# 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)"'

Jika klien Anda terhubung ke host selain IP ini (misalnya, nama DNS Anda sendiri di depan load balancer internal), gunakan host tersebut.

Langkah 2: Ambil sertifikat CA root saat ini dan yang akan datang

Baca kolom caCertificates[] dari organizations.get. Selama rotasi, array ini berisi CA root saat ini dan yang baru, yang masing-masing dienkode base64:

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

Dekode setiap entri ke format PEM dan periksa periode validitas untuk mengidentifikasi sertifikat baru:

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

Sertifikat dengan tanggal notAfter yang lebih baru adalah root CA baru.

Langkah 3: Tambahkan CA root baru ke truststore Anda

Tambahkan sertifikat CA root baru ke setiap truststore klien yang saat ini memercayai CA root Apigee. Biarkan CA root saat ini tetap ada hingga cutover selesai, sehingga koneksi terus berfungsi selama periode cutover. Setelah peralihan, Anda dapat menghapus CA root lama dari truststore Anda.

Prosedur yang tepat bergantung pada klien. Kasus umum mencakup:

  • Menambahkan sertifikat ke truststore tingkat OS (misalnya, /etc/ssl/certs/ pada sistem berbasis Debian, diikuti dengan update-ca-certificates).
  • Menambahkan sertifikat ke truststore yang dikelola aplikasi (misalnya, keystore cacerts Java, paket ssl_trusted_certificate Nginx, atau paket kepercayaan validation_context Envoy).
  • Menambahkan sertifikat ke Secret atau ConfigMap Kubernetes yang di-mount ke pod workload Anda.

Langkah 4: Pastikan koneksi berfungsi dengan CA root baru

Setelah Anda menyiapkan CA root baru, verifikasi bahwa permintaan HTTPS ke runtime Apigee berhasil saat Anda hanya memercayai sertifikat baru:

# 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

Jika perintah ini berhasil, klien Anda siap untuk peralihan. Jika gagal, klien belum memercayai root CA baru — buka kembali Langkah 3.

Contoh: Perutean internal (VPC), Opsi TLS 2

Contoh ini menunjukkan langkah-langkah rotasi untuk pola akses yang didokumentasikan dalam Perutean internal (VPC), Opsi TLS 2, di mana klien terhubung langsung ke load balancer internal Apigee dan memvalidasi sertifikat yang ditandatangani sendiri Apigee. Pola akses ini adalah yang paling sering terpengaruh oleh rotasi.

Sebelum peralihan:

  1. Dapatkan IP load balancer internal Apigee: 
    export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
  | jq -r '.instances[0].host')
  2. Ambil CA root saat ini dan yang baru ke dalam file terpisah dan identifikasi CA yang baru: 
    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. Buat gabungan truststore yang berisi CA root saat ini dan yang baru, lalu gunakan untuk permintaan pengujian Anda: 
    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

    Jika permintaan ini berhasil, deploy cacert-combined.crt sebagai truststore klien Anda. Truststore gabungan akan terus memvalidasi sertifikat saat ini hari ini dan akan memvalidasi sertifikat baru setelah peralihan.

Setelah peralihan (biasanya dalam beberapa hari setelah tanggal peralihan), konfirmasi rotasi dengan memverifikasi bahwa koneksi masih berhasil saat Anda hanya memercayai sertifikat baru:

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

Jika permintaan ini berhasil, Anda dapat menghapus CA root lama dengan aman dari truststore Anda.

Notifikasi

Apigee mengirimkan notifikasi kepada pemilik project dan pemilik organisasi project Google Cloud Anda di awal setiap tahap rotasi. Setiap notifikasi mencakup nama panggung, tanggal panggung akan diterapkan ke organisasi Anda, dan link ke halaman ini.

Notifikasi Tindakan pelanggan yang direkomendasikan
1. Sertifikat baru dipublikasikan
(~1 tahun sebelum masa berlaku habis)		 Ambil CA root baru dari caCertificates[] dan tambahkan ke setiap truststore klien yang saat ini memercayai CA root Apigee. Lihat Cara mempersiapkan rotasi.
2. Migrasi sistem sertifikat entitas akhir
(~60 hari sebelum masa berlaku habis)		 Pastikan semua klien Anda memercayai CA root baru sebelum tahap ini diterapkan di wilayah Anda. Setelah tahap ini, klien yang hanya memercayai CA root lama tidak dapat terhubung.
3. Sertifikat lama ditarik
(~30 hari sebelum masa berlaku berakhir)		 Setelah tahap ini diterapkan ke semua wilayah Anda, Anda dapat menghapus CA root lama dengan aman dari truststore klien Anda.
4. Rotasi selesai
(pada tanggal habis masa berlaku asli)		 Tindakan tidak diperlukan. CA root lama telah dihapus secara permanen dan CA root baru adalah satu-satunya CA root untuk organisasi Anda.

Jika Anda tidak menerima notifikasi rotasi dan Anda menggunakan salah satu pola akses yang tercantum dalam Siapa yang terpengaruh oleh rotasi, hubungi dukungan Apigee untuk mengonfirmasi penerima notifikasi untuk organisasi Anda.

Langkah berikutnya