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), atau`acm-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](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html) 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 ](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-private.html) 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](#rest-api-acm-client-certificates-requirements). Untuk informasi selengkapnya tentang menerbitkan sertifikat pribadi, lihat [ Menerbitkan sertifikat entitas akhir pribadi ](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html) 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 menggunakan`aws acm import-certificate`. Impor menghasilkan sertifikat ACM ARN yang Anda gunakan pada langkah berikut. Saat Anda menjalankan`aws 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](https://console.aws.amazon.com/apigateway).
1. Pilih REST API Anda.
1. Memilih **Tahapan**.
1. Di ** bagian ** Detail Stage, pilih ** Edit**.
1. Untuk sertifikat ** Klien**, pilih sertifikat ACM Anda dari daftar dropdown.
1. 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.
1. Periksa apakah backend Anda mendapatkan sertifikat klien selama jabat tangan TLS.
1. 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 (seperti`CA: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 ](https://docs.aws.amazon.com/acm/latest/userguide/import-certificate.html) 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](https://docs.aws.amazon.com/acm/latest/userguide/supported-events.html). 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](https://docs.aws.amazon.com/apigateway/latest/api/API_GetStage.html). Untuk melihat detail sertifikat, gunakan API ACM [ DescribeCertificate ](https://docs.aws.amazon.com/acm/latest/APIReference/API_DescribeCertificate.html) dan [ GetCertificate](https://docs.aws.amazon.com/acm/latest/APIReference/API_GetCertificate.html).
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. `DeleteClientCertificate`API`GetClientCertificate`,`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.