View a markdown version of this page

Gunakan sertifikat ACM Anda sendiri untuk backend bersama TLS di API Gateway - Amazon API Gateway
PrasyaratLangkah 1: Impor sertifikat, atau menerbitkannya melalui AWS Private Certificate AuthorityLangkah 2: Konfigurasikan tahap API untuk menggunakan sertifikat ACMLangkah 3: Verifikasi konfigurasiPersyaratan sertifikatPerpanjangan dan propagasi sertifikatPerilaku dan keterbatasan sertifikat ACM

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Gunakan sertifikat ACM Anda sendiri untuk backend bersama TLS di API Gateway

Anda dapat mengonfigurasi API Gateway untuk menyajikan CA-signed sertifikat Anda sendiri ke layanan backend. Impor sertifikat Anda ke AWS Certificate Manager (ACM), atau keluarkan satu melalui AWS Private Certificate Authority. Kemudian, tautkan sertifikat ACM ARN ke tahap API Anda.

Prasyarat

Sebelum mengonfigurasi sertifikat klien ACM, Anda harus memiliki yang berikut:

  • AWS Certificate Manager akses di Wilayah yang sama dengan API Anda.

  • Izin IAM: acm:ImportCertificate dan acm:DescribeCertificate (untuk impor Opsi A), atau acm:RequestCertificate (untuk Opsi B), atauacm-pca:IssueCertificate,acm-pca:GetCertificate, dan acm:ImportCertificate (untuk Opsi C).

  • REST API dikerahkan ke panggung.

Langkah 1: Impor sertifikat, atau menerbitkannya melalui AWS Private Certificate Authority

Anda dapat mengimpor sertifikat dari PKI yang ada atau mengeluarkan sertifikat baru melalui AWS Private Certificate Authority. Kedua jalur menghasilkan sertifikat ACM ARN yang Anda gunakan pada langkah berikut.

catatan

Sertifikat publik ACM tidak didukung untuk otentikasi klien backend. Efektif 11 Juni 2025, AWS Certificate Manager tidak lagi mengeluarkan sertifikat publik dengan penggunaan kunci clientAuth diperpanjang (EKU). Fitur ini membutuhkan EKU itu, jadi gunakan sertifikat yang Anda impor ke ACM, atau yang dikeluarkan melalui. AWS Private Certificate Authority

catatan

Buat sertifikat ACM di Wilayah yang sama AWS dengan REST API yang akan menggunakannya. Sertifikat ACM adalah sumber daya Regional, jadi sertifikat harus ada di Wilayah API Anda.

Opsi A: Impor dari PKI Anda yang ada

Untuk mengimpor sertifikat klien dan kunci pribadinya ke ACM, jalankan perintah berikut. Untuk informasi lebih lanjut, lihat Mengimpor sertifikat di AWS Certificate Manager Panduan Pengguna.

aws acm import-certificate \
  --certificate fileb://client-cert.pem \
  --private-key fileb://private-key.pem \
  --certificate-chain fileb://ca-chain.pem \
  --region region

Perintah mengembalikan sertifikat ACM ARN. Catat nilai ini untuk langkah berikut.

Opsi B: Minta sertifikat melalui AWS Private Certificate Authority (ACM-managed)

Untuk meminta sertifikat pribadi yang dikelola ACM dan dapat diperpanjang secara otomatis, jalankan perintah berikut. Untuk informasi selengkapnya, lihat Meminta sertifikat pribadi di Panduan AWS Certificate Manager Pengguna.

aws acm request-certificate \
  --domain-name www.example.com \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --region region

Perintah mengembalikan sertifikat ACM ARN. Catat nilai ini untuk langkah berikut.

Opsi C: Masalah melalui AWS Private Certificate Authority dan impor ke ACM

Jika Anda memerlukan kontrol langsung atas parameter sertifikat (seperti ekstensi khusus atau algoritma penandatanganan), Anda dapat mengeluarkan sertifikat melalui AWS Private Certificate Authority dan kemudian mengimpornya ke ACM. Sertifikat yang diimpor dengan cara ini tidak diperpanjang secara otomatis oleh ACM. Pastikan sertifikat memenuhi persyaratan sertifikat. Untuk informasi selengkapnya tentang menerbitkan sertifikat pribadi, lihat Menerbitkan sertifikat entitas akhir pribadi di Panduan AWS Private Certificate Authority Pengguna.

aws acm-pca issue-certificate \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --csr fileb://csr.pem \
  --signing-algorithm SHA256WITHRSA \
  --validity Value=365,Type=DAYS
Mengambil dan mengimpor sertifikat

Per issue-certificate intah mengembalikan AWS Private Certificate Authority sertifikat ARN, bukan ARN ACM. Untuk menggunakan sertifikat ini dengan API Gateway, ambil menggunakan aws acm-pca get-certificate dan kemudian impor ke ACM menggunakanaws acm import-certificate. Impor menghasilkan sertifikat ACM ARN yang Anda gunakan pada langkah berikut. Saat Anda menjalankanaws acm import-certificate, set --region el ke Wilayah API Anda sehingga sertifikat ACM dibuat di sana.

Langkah 2: Konfigurasikan tahap API untuk menggunakan sertifikat ACM

Setelah Anda memiliki sertifikat ACM ARN, siapkan tahap API Anda untuk menyajikan sertifikat ke backend Anda.

Untuk mengkonfigurasi panggung (konsol)

  1. Buka konsol API Gateway di https://console.aws.amazon.com/apigateway.

  2. Pilih REST API Anda.

  3. Memilih Tahapan.

  4. Di bagian Detail Stage, pilih Edit.

  5. Untuk sertifikat Klien, pilih sertifikat ACM Anda dari daftar dropdown.

  6. Pilih Simpan perubahan.

Untuk mengkonfigurasi panggung (AWS CLI)

Jalankan perintah berikut:

aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
catatan

API Gateway menggunakan clientCertificateId bidang yang sama untuk Gateway-generated sertifikat ACM dan API. Saat Anda memberikan sertifikat ACM ARN, API Gateway secara otomatis mendeteksi format dan menggunakan ACM-managed alur kerja.

Langkah 3: Verifikasi konfigurasi

Untuk memverifikasi bahwa API Gateway mengirimkan sertifikat ke backend Anda, selesaikan langkah-langkah berikut:

Backend harus meminta sertifikat klien

Backend Anda harus dikonfigurasi untuk meminta sertifikat klien selama jabat tangan TLS. Jika backend tidak memintanya, API Gateway tidak menampilkan sertifikat.

  1. Memanggil titik akhir API Anda.

  2. Periksa apakah backend Anda mendapatkan sertifikat klien selama jabat tangan TLS.

  3. Periksa apakah backend Anda menerima sertifikat dan mengembalikan respons yang berhasil.

Jika backend menolak sertifikat, verifikasi bahwa rantai sertifikat dapat divalidasi terhadap penyimpanan kepercayaan backend.

Persyaratan sertifikat

Sertifikat daun yang Anda konfigurasikan harus memenuhi persyaratan berikut.

Persyaratan sertifikat klien ACM
Persyaratan Deskripsi
Panjang rantai maksimum 5 sertifikat
Validitas Sertifikat tidak boleh kedaluwarsa atau belum valid saat Anda mengonfigurasinya
Region Sertifikat ACM harus berada di Wilayah yang sama dengan API
Akun Sertifikat ACM harus berada di akun yang sama dengan API
Penggunaan Kunci Diperpanjang (EKU) Jika ada, harus disertakanclientAuth. Jika tidak ada, sertifikat diterima.
Penggunaan Kunci (KU) Jika ada, harus menyertakan digitalSignature ataukeyAgreement. Jika tidak ada, sertifikat diterima.
Algoritma kunci Harus salah satu dari: RSA 2048, RSA 3072, RSA 4096, ECDSA (EC_PRIME256v1), ECDSA (EC_SECP384R1), P-256 atau ECDSA (EC_SECP521R1) P-384 P-521
Status sertifikat ACM Harus ISSUED
catatan

API Gateway tidak memvalidasi rantai kepercayaan antara sertifikat leaf dan intermediet. API Gateway juga tidak memvalidasi maksud sertifikat atau batasan dasar (sepertiCA:TRUE) pada sertifikat perantara. Backend Anda melakukan validasi ini selama jabat tangan TLS.

Perpanjangan dan propagasi sertifikat

Ketika sertifikat berubah di ACM, API Gateway mendeteksi pembaruan dan menyebarkan sertifikat baru secara otomatis. Anda tidak perlu menyebarkan ulang stage Anda, dan API Anda tidak mengalami downtime selama rotasi.

Penyebaran sertifikat pada akhirnya konsisten. Selama pembaruan, backend Anda mungkin menerima sertifikat lama atau baru sampai propagasi selesai.

Bagaimana sertifikat diperpanjang tergantung pada bagaimana sertifikat itu dikeluarkan:

  • Sertifikat yang dikeluarkan melalui AWS Private Certificate Authority (ACM-managed) (Opsi B) - ACM memperbarui sertifikat ini secara otomatis. API Gateway mendeteksi pembaruan dan pembaruan secara otomatis.

  • Sertifikat yang dikeluarkan oleh AWS Private Certificate Authority dan diimpor (Opsi C) — ACM tidak memperpanjang sertifikat impor secara otomatis. Anda harus mengimpor kembali sertifikat yang diperbarui. Setelah Anda mengimpor ulang sertifikat, API Gateway mendeteksi perubahan dan memperbarui secara otomatis.

  • Sertifikat yang diimpor dari PKI Anda (Opsi A) — Anda harus mengimpor ulang sertifikat yang diperbarui ke ACM. Setelah Anda mengimpor ulang sertifikat, API Gateway mendeteksi perubahan dan memperbarui secara otomatis.

ACM mengirimkan pemberitahuan kedaluwarsa sertifikat melalui Amazon EventBridge. Anda dapat menggunakan notifikasi ini untuk mengatur alarm sebelum sertifikat kedaluwarsa.

Perilaku dan keterbatasan sertifikat ACM

Melihat sertifikat yang dikonfigurasi

Sertifikat ACM tidak muncul dalam respon GetClientCertificate atau GetClientCertificates API. Untuk melihat sertifikat ACM ARN yang dikonfigurasi pada panggung, gunakan GetStage. Untuk melihat detail sertifikat, gunakan API ACM DescribeCertificate dan GetCertificate.

Gunakan kembali di seluruh tahapan

Anda dapat melampirkan sertifikat ACM yang sama ke beberapa tahap. Setiap tahap secara independen mereferensikan sertifikat oleh ARN-nya.

API sertifikat klien tidak berlaku untuk sertifikat ACM

Sertifikat ACM bukan Gateway-managed sumber daya API. DeleteClientCertificateAPIGetClientCertificate,UpdateClientCertificate, dan mengembalikan NotFoundException ketika dipanggil dengan sertifikat ACM ARN. Gunakan API ACM untuk mengelola siklus hidup sertifikat.

Pembersihan asosiasi sertifikat otomatis

Saat Anda menghapus sertifikat ACM dari tahap, memperbarui tahap untuk menggunakan sertifikat yang berbeda, atau menghapus stage atau REST API, API Gateway membersihkan asosiasi sertifikat secara otomatis. Tidak diperlukan tindakan manual.

Menghapus sertifikat ACM

ACM tidak mengizinkan Anda untuk menghapus sertifikat sementara API Gateway memiliki asosiasi aktif dengannya. Untuk menghapus sertifikat dari ACM, pertama-tama hapus dari semua tahapan yang mereferensikannya.