Memerlukan sertifikat klien untuk API Anda dengan otentikasi TLS bersama di API Gateway

Otentikasi TLS bersama memerlukan otentikasi dua arah antara klien dan server. Dengan TLS bersama, klien harus menunjukkan X.509 sertifikat untuk memverifikasi identitas mereka untuk mengakses API Anda. Mutual TLS adalah persyaratan umum untuk Internet of Things (IoT) dan aplikasi bisnis-ke-bisnis.

Anda dapat menggunakan TLS bersama dengan operasi otorisasi dan otentikasi lainnya yang didukung API Gateway. API Gateway meneruskan sertifikat yang diberikan klien ke otorisasi Lambda dan integrasi backend.

Prasyarat untuk TLS bersama

Untuk mengkonfigurasi TLS bersama, Anda perlu:

Nama domain kustom

Untuk mengaktifkan TLS bersama untuk REST API, Anda harus mengonfigurasi nama domain khusus untuk API Anda. Anda dapat mengaktifkan TLS bersama untuk nama domain kustom, dan kemudian memberikan nama domain khusus kepada klien. Untuk mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS bersama, klien harus menunjukkan sertifikat yang Anda percayai dalam permintaan API. Anda dapat menemukan informasi lebih lanjut diNama domain khusus untuk REST publik APIs di API Gateway.

Penggunaan AWS Certificate Manager sertifikat yang dikeluarkan

Anda dapat meminta sertifikat tepercaya publik langsung dari ACM atau mengimpor sertifikat publik atau yang ditandatangani sendiri. Untuk mengatur sertifikat di ACM, buka AC M. 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 AWS Private Certificate Authority bersama TLS, API Gateway memerlukan sertifikat 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 memilikinyaownershipVerificationCertificate, buka 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 nama domain akan dikunci. Anda perlu memperbarui ownershipVerificationCertificateArn dengan valid ownershipVerificationCertificate sebelum Anda dapat membuat perubahan lainnya. Tidak ownershipVerificationCertificate dapat digunakan sebagai sertifikat server untuk domain TLS bersama 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 bersama, buat truststore X.509 sertifikat yang Anda percayai untuk mengakses API Anda.

Anda harus menyertakan rantai kepercayaan lengkap, mulai dari sertifikat CA yang menerbitkan, 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 berasal dari otoritas sertifikat publik atau swasta. Sertifikat dapat memiliki panjang rantai maksimum empat. Anda juga dapat memberikan sertifikat yang ditandatangani sendiri. Algoritma 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

Berikut ini adalah contoh seperti apa file.pem mungkin terlihat.

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

Per AWS CLI intah cp berikut diunggah certificates.pem ke bucket Amazon S3 Anda:

aws s3 cp certificates.pem s3://bucket-name

Mengkonfigurasi TLS bersama untuk nama domain khusus

Untuk mengonfigurasi TLS bersama untuk REST API, Anda harus menggunakan nama domain kustom Regional untuk API Anda, dengan kebijakan TLS_1_2 keamanan. Untuk informasi selengkapnya tentang memilih kebijakan keamanan, lihatPilih kebijakan keamanan untuk domain kustom Anda di API Gateway.

Setelah mengupload truststore ke Amazon S3, Anda dapat mengonfigurasi nama domain kustom untuk menggunakan TLS bersama. Create-domain-name berikut ini membuat nama domain ku stom dengan TLS bersama:

aws apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://bucket-name/key-name

Setelah membuat nama domain, Anda harus mengonfigurasi catatan DNS dan pemetaan jalur dasar untuk operasi API. Untuk mempelajari selengkapnya, lihat Siapkan nama domain kustom Regional di API Gateway.

Memanggil API dengan menggunakan nama domain khusus yang membutuhkan TLS bersama

Untuk memanggil API dengan TLS bersama diaktifkan, klien harus menyajikan sertifikat tepercaya dalam permintaan API. Saat klien mencoba memanggil 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.

Per curl intah contoh 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 melakukan 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 Anda memperbarui nama domain kustom 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.

Perintah update-domain-name berikut memperbarui nama domain kustom untuk menggunakan versi truststore baru:

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

Nonaktifkan TLS bersama

Pembaruan domain-name berikut menonaktifkan TLS bersama:

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

Memecahkan masalah TLS bersama untuk REST API Anda

Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat mengaktifkan TLS bersama.

Pemecahan masalah peringatan sertifikat

Saat membuat nama domain khusus dengan TLS bersama, 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 dapat 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 SAN dalam sertifikat tidak mencakup nama domain. Sesuatu mungkin tidak dikonfigurasi dengan benar atau sertifikat yang tidak valid diimpor. Anda perlu mengimpor ulang sertifikat yang valid ke ACM. Untuk informasi selengkapnya tentang validasi, lihat Mem validasi kepemilikan domain.

PENDING_OWNERSHIP_VERIFICATION: Ini berarti sertifikat Anda yang diverifikasi sebelumnya telah kedaluwarsa dan ACM tidak dapat memperpanjangnya secara otomatis. Anda perlu memperbarui sertifikat atau meminta sertifikat baru. Informasi lebih lanjut tentang pembaruan sertifikat dapat ditemukan di panduan pemecahan masalah pembaruan sertifikat terkelola ACM.

Memecahkan masalah sertifikat yang dikembalikan salah

Saat memigrasikan sertifikat khusus dari nama domain yang memenuhi syarat (FQDN) ke nama domain pelanggan wildcard, API Gateway mungkin mengembalikan sertifikat untuk FQDN alih-alih nama domain wildcard.

Perintah berikut menampilkan sertifikat mana yang dikembalikan oleh API Gateway:

openssl s_client -connect hostname:port

Jika sertifikat yang dihasilkan adalah untuk FQDN, hubungi Dukungan untuk membuka tiket.