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 lain yang didukung API Gateway. API Gateway meneruskan sertifikat yang disediakan klien kepada otorisasi Lambda dan integrasi backend.

Prasyarat untuk TLS timbal balik

Untuk mengkonfigurasi TLS timbal balik yang Anda butuhkan:

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 diNama domain khusus untuk HTTP APIs di API Gateway.

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. 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 memilikiownershipVerificationCertificate, pergi ke 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:

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:

Unggah truststore ke bucket Amazon S3 dalam satu file

-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
...

AWS CLI Perintah cp 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, lihatMenyiapkan nama domain kustom Regional di API Gateway.

Setelah Anda mengunggah truststore Anda ke Amazon S3, Anda dapat mengonfigurasi nama domain khusus Anda untuk menggunakan TLS bersama. Berikut ini create-domain-namemembuat 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 Menyiapkan nama domain kustom Regional di API Gateway.

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.keyadalah 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:

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 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-namePerintah 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-namePerintah 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 <certSubject> 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 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.

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.