Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Cara mengaktifkan otentikasi TLS timbal balik untuk HTTP Anda APIs di API Gateway
Mutual TLS otentikasi membutuhkan otentikasi dua arah antara klien dan server. Dengan TLS bersama, klien harus menunjukkan sertifikat X.509 untuk memverifikasi identitas mereka untuk mengakses API Anda. Mutual TLS adalah persyaratan umum untuk Internet of Things (IoT) business-to-business dan aplikasi.
Anda dapat menggunakan TLS timbal balik bersama dengan [operasi otorisasi dan otentikasi](apigateway-control-access-to-api.md) lain yang didukung API Gateway. API Gateway meneruskan sertifikat yang disediakan klien kepada otorisasi Lambda dan integrasi backend.
**penting**
Secara default, klien dapat memanggil API Anda dengan menggunakan `execute-api` titik akhir yang dihasilkan API Gateway untuk API Anda. Untuk memastikan bahwa klien dapat mengakses API Anda hanya dengan menggunakan nama domain khusus dengan TLS timbal balik, nonaktifkan titik `execute-api` akhir default. Untuk mempelajari selengkapnya, lihat [Nonaktifkan titik akhir default untuk HTTP APIs](http-api-disable-default-endpoint.md).
## Prasyarat untuk TLS timbal balik
Untuk mengkonfigurasi TLS timbal balik yang Anda butuhkan:
+ Sebuah nama domain kustom
+ Setidaknya satu sertifikat yang dikonfigurasi AWS Certificate Manager untuk nama domain kustom Anda
+ Truststore yang dikonfigurasi dan diunggah ke Amazon S3
### Nama domain kustom
Untuk mengaktifkan TLS timbal balik untuk API HTTP, Anda harus mengonfigurasi nama domain khusus untuk API Anda. Anda dapat mengaktifkan TLS timbal balik untuk nama domain khusus, dan kemudian memberikan nama domain khusus kepada klien. Untuk mengakses API dengan menggunakan nama domain kustom yang mengaktifkan TLS bersama, klien harus menunjukkan sertifikat yang Anda percayai dalam permintaan API. Anda dapat menemukan informasi lebih lanjut di[Nama domain khusus untuk HTTP APIs di API Gateway](http-api-custom-domain-names.md).
### Menggunakan sertifikat AWS Certificate Manager yang dikeluarkan
Anda dapat meminta sertifikat tepercaya publik langsung dari ACM atau mengimpor sertifikat publik atau yang ditandatangani sendiri. Untuk menyiapkan sertifikat di ACM, buka [ACM](https://console.aws.amazon.com/acm/). Jika Anda ingin mengimpor sertifikat, lanjutkan membaca di bagian berikut.
### Menggunakan impor atau AWS Private Certificate Authority sertifikat
Untuk menggunakan sertifikat yang diimpor ke ACM atau sertifikat dari TLS AWS Private Certificate Authority bersama, API Gateway memerlukan yang `ownershipVerificationCertificate` dikeluarkan oleh ACM. Sertifikat kepemilikan ini hanya digunakan untuk memverifikasi bahwa Anda memiliki izin untuk menggunakan nama domain. Ini tidak digunakan untuk jabat tangan TLS. Jika Anda belum memiliki`ownershipVerificationCertificate`, pergi ke [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/)untuk mengaturnya.
Anda harus menjaga sertifikat ini tetap berlaku selama masa pakai nama domain Anda. Jika sertifikat kedaluwarsa dan perpanjangan otomatis gagal, semua pembaruan pada nama domain akan dikunci. Anda perlu memperbarui `ownershipVerificationCertificateArn` dengan valid `ownershipVerificationCertificate` sebelum Anda dapat membuat perubahan lainnya. Ini `ownershipVerificationCertificate` tidak dapat digunakan sebagai sertifikat server untuk domain TLS timbal balik lainnya di API Gateway. Jika sertifikat langsung diimpor kembali ke ACM, penerbit harus tetap sama.
### Mengkonfigurasi truststore Anda
Truststores adalah file teks dengan ekstensi `.pem` file. Mereka adalah daftar sertifikat tepercaya dari Otoritas Sertifikat. Untuk menggunakan TLS timbal balik, buat truststore sertifikat X.509 yang Anda percayai untuk mengakses API Anda.
Anda harus menyertakan rantai kepercayaan lengkap, mulai dari sertifikat CA penerbitan, hingga sertifikat CA root, di truststore Anda. API Gateway menerima sertifikat klien yang dikeluarkan oleh CA mana pun yang ada dalam rantai kepercayaan. Sertifikat dapat dari otoritas sertifikat publik atau swasta. Sertifikat dapat memiliki panjang rantai maksimum empat. Anda juga dapat memberikan sertifikat yang ditandatangani sendiri. Algoritma hashing berikut didukung di truststore:
+ SHA-256 atau lebih kuat
+ RSA-2048 atau lebih kuat
+ ECDSA-256 atau lebih kuat
API Gateway memvalidasi sejumlah properti sertifikat. Anda dapat menggunakan otorisasi Lambda untuk melakukan pemeriksaan tambahan saat klien memanggil API, termasuk memeriksa apakah sertifikat telah dicabut. API Gateway memvalidasi properti berikut:
| Validasi | Deskripsi |
| --- | --- |
| Sintaks X.509 | Sertifikat harus memenuhi persyaratan sintaks X.509. |
| Integritas | Konten sertifikat tidak boleh diubah dari yang ditandatangani oleh otoritas sertifikat dari truststore. |
| Validitas | Masa berlaku sertifikat harus terkini. |
| Nama rantai/rantai kunci | Nama dan subjek sertifikat harus membentuk rantai yang tidak terputus. Sertifikat dapat memiliki panjang rantai maksimum empat. |
### Unggah truststore ke bucket Amazon S3 dalam satu file
**Example sertifikat.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
AWS CLI Perintah [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) berikut diunggah `certificates.pem` ke bucket Amazon S3 Anda:
```
aws s3 cp certificates.pem s3://bucket-name
```
## Mengkonfigurasi TLS timbal balik untuk nama domain khusus
Untuk mengonfigurasi TLS timbal balik untuk API HTTP, Anda harus menggunakan nama domain kustom Regional untuk API Anda, dengan versi TLS minimal 1.2. Untuk mempelajari selengkapnya tentang membuat dan mengonfigurasi nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
**catatan**
Mutual TLS tidak didukung untuk pribadi APIs.
Setelah Anda mengunggah truststore Anda ke Amazon S3, Anda dapat mengonfigurasi nama domain khusus Anda untuk menggunakan TLS bersama. Berikut ini [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)membuat nama domain kustom dengan TLS timbal balik:
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
Setelah membuat nama domain, Anda harus mengonfigurasi catatan DNS dan pemetaan basepath untuk operasi API. Untuk mempelajari selengkapnya, lihat [Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
## Memanggil API dengan menggunakan nama domain khusus yang membutuhkan TLS timbal balik
Untuk menjalankan API dengan TLS timbal balik diaktifkan, klien harus menunjukkan sertifikat tepercaya dalam permintaan API. Saat klien mencoba menjalankan API Anda, API Gateway mencari penerbit sertifikat klien di truststore Anda. Agar API Gateway dapat melanjutkan permintaan, penerbit sertifikat dan rantai kepercayaan lengkap hingga sertifikat CA root harus ada di truststore Anda.
Contoh `curl` perintah berikut mengirimkan permintaan ke `api.example.com,` yang termasuk `my-cert.pem` dalam permintaan. `my-key.key`adalah kunci pribadi untuk sertifikat.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
API Anda dipanggil hanya jika truststore Anda mempercayai sertifikat. Kondisi berikut akan menyebabkan API Gateway gagal dalam jabat tangan TLS dan menolak permintaan dengan kode `403` status. Jika sertifikat Anda:
+ tidak dipercaya
+ kedaluwarsa
+ tidak menggunakan algoritme yang didukung
**catatan**
API Gateway tidak memverifikasi apakah sertifikat telah dicabut.
## Memperbarui truststore Anda
Untuk memperbarui sertifikat di truststore Anda, unggah bundel sertifikat baru ke Amazon S3. Kemudian, Anda dapat memperbarui nama domain kustom Anda untuk menggunakan sertifikat yang diperbarui.
Gunakan versi [Amazon S3 untuk mempertahankan beberapa versi](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) truststore Anda. Saat memperbarui nama domain khusus untuk menggunakan versi truststore baru, API Gateway mengembalikan peringatan jika sertifikat tidak valid.
API Gateway menghasilkan peringatan sertifikat hanya ketika Anda memperbarui nama domain Anda. API Gateway tidak memberi tahu Anda jika sertifikat yang diunggah sebelumnya kedaluwarsa.
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui nama domain kustom untuk menggunakan versi truststore baru:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## Nonaktifkan TLS timbal balik
Untuk menonaktifkan TLS timbal balik untuk nama domain kustom, hapus truststore dari nama domain kustom Anda, seperti yang ditunjukkan pada perintah berikut.
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui nama domain khusus untuk menghapus truststore dari nama domain kustom Anda:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## Memecahkan masalah TLS timbal balik untuk HTTP API Anda
Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat mengaktifkan TLS timbal balik.
### Memecahkan masalah peringatan sertifikat
Saat membuat nama domain khusus dengan TLS timbal balik, API Gateway mengembalikan peringatan jika sertifikat di truststore tidak valid. Ini juga dapat terjadi saat memperbarui nama domain khusus untuk menggunakan truststore baru. Peringatan menunjukkan masalah dengan sertifikat dan subjek sertifikat yang menghasilkan peringatan. Mutual TLS masih diaktifkan untuk API Anda, tetapi beberapa klien mungkin tidak dapat mengakses API Anda.
Anda harus memecahkan kode sertifikat di truststore Anda untuk mengidentifikasi sertifikat mana yang menghasilkan peringatan. Anda dapat menggunakan alat seperti `openssl` untuk memecahkan kode sertifikat dan mengidentifikasi subjek mereka.
Perintah berikut menampilkan isi sertifikat, termasuk subjeknya:
```
openssl x509 -in certificate.crt -text -noout
```
Perbarui atau hapus sertifikat yang menghasilkan peringatan, lalu unggah truststore baru ke Amazon S3. Setelah mengunggah truststore baru, perbarui nama domain kustom Anda untuk menggunakan truststore baru.
### Memecahkan masalah konflik nama domain
Kesalahan `"The certificate subject conflicts with an existing certificate from a different issuer."` berarti beberapa Otoritas Sertifikat telah mengeluarkan sertifikat untuk domain ini. Untuk setiap subjek dalam sertifikat, hanya ada satu penerbit di API Gateway untuk domain TLS bersama. Anda harus mendapatkan semua sertifikat Anda untuk subjek itu melalui satu penerbit. Jika masalahnya adalah dengan sertifikat yang tidak Anda kendalikan tetapi Anda dapat membuktikan kepemilikan nama domain, [hubungi Dukungan](https://console.aws.amazon.com/support/cases#/create) untuk membuka tiket.
### Memecahkan masalah pesan status nama domain
`PENDING_CERTIFICATE_REIMPORT`: Ini berarti Anda mengimpor ulang sertifikat ke ACM dan validasi gagal karena sertifikat baru memiliki SAN (nama alternatif subjek) yang tidak tercakup oleh `ownershipVerificationCertificate` atau subjek atau SANs dalam sertifikat tidak mencakup nama domain. Sesuatu mungkin dikonfigurasi dengan tidak benar atau sertifikat yang tidak valid diimpor. Anda perlu mengimpor ulang sertifikat yang valid ke ACM. Untuk informasi selengkapnya tentang validasi, lihat [Memvalidasi kepemilikan domain](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html).
`PENDING_OWNERSHIP_VERIFICATION`: Ini berarti sertifikat Anda yang telah diverifikasi sebelumnya telah kedaluwarsa dan ACM tidak dapat memperbaruinya secara otomatis. Anda perlu memperbarui sertifikat atau meminta sertifikat baru. Informasi lebih lanjut tentang perpanjangan sertifikat dapat ditemukan di panduan perpanjangan sertifikat [terkelola pemecahan masalah ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html).