Cara mengaktifkan TLS otentikasi timbal balik untuk Anda REST APIs di API Gateway

TLSOtentikasi timbal balik membutuhkan otentikasi dua arah antara klien dan server. Dengan saling menguntungkanTLS, klien harus menunjukkan sertifikat X.509 untuk memverifikasi identitas mereka untuk mengakses Anda. API Mutual TLS adalah persyaratan umum untuk Internet of Things (IoT) dan business-to-business aplikasi.

Anda dapat menggunakan timbal balik TLS bersama dengan operasi otorisasi dan otentikasi lain yang didukung API Gateway. APIGateway meneruskan sertifikat yang diberikan klien kepada otorisasi Lambda dan integrasi backend.

penting

Secara default, klien dapat memanggil Anda API dengan menggunakan execute-api titik akhir yang dihasilkan API Gateway untuk Anda. API Untuk memastikan bahwa klien dapat mengakses Anda API hanya dengan menggunakan nama domain khusus dengan timbal balikTLS, nonaktifkan execute-api titik akhir default. Untuk mempelajari selengkapnya, lihat Nonaktifkan titik akhir default untuk REST API.

Prasyarat untuk saling menguntungkan TLS

Untuk mengkonfigurasi timbal balik yang TLS Anda butuhkan:

• Nama domain kustom Regional

• 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 mutual TLS untuk a RESTAPI, Anda harus mengkonfigurasi nama domain kustom untuk AndaAPI. Anda dapat mengaktifkan mutual TLS untuk nama domain kustom, dan kemudian memberikan nama domain kustom kepada klien. Untuk mengakses API dengan menggunakan nama domain kustom yang saling TLS diaktifkan, klien harus menunjukkan sertifikat yang Anda percayai dalam API permintaan. Anda dapat menemukan informasi lebih lanjut diNama domain khusus untuk REST 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 sertifikatACM, 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 dalam ACM atau sertifikat dari AWS Private Certificate Authority dengan timbal balikTLS, API Gateway perlu ownershipVerificationCertificate dikeluarkan olehACM. Sertifikat kepemilikan ini hanya digunakan untuk memverifikasi bahwa Anda memiliki izin untuk menggunakan nama domain. Ini tidak digunakan untuk TLS jabat tangan. 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. ownershipVerificationCertificateTidak dapat digunakan sebagai sertifikat server untuk TLS domain timbal balik lain di API Gateway. Jika sertifikat langsung diimpor kembali keACM, 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 timbal balikTLS, buat truststore sertifikat X.509 yang Anda percayai untuk mengakses sertifikat Anda. API

Anda harus menyertakan rantai kepercayaan lengkap, mulai dari sertifikat CA penerbitan, hingga sertifikat CA root, di truststore Anda. APIGateway menerima sertifikat klien yang dikeluarkan oleh CA apa 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 berikut didukung di truststore:

• SHA-256 atau lebih kuat

• RSA-2048 atau lebih kuat

• ECDSA-256 atau ECDSA -384

APIGateway memvalidasi sejumlah properti sertifikat. Anda dapat menggunakan otorisasi Lambda untuk melakukan pemeriksaan tambahan saat klien memanggilAPI, termasuk memeriksa apakah sertifikat telah dicabut. APIGateway 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

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

contoh sertifikat.pem

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

AWS CLI Perintah berikut akan diunggah certificates.pem ke bucket Amazon S3 Anda.

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

Bucket Amazon S3 Anda harus memiliki izin baca agar Gateway mengizinkan API Gateway mengakses API truststore Anda.

Mengkonfigurasi timbal balik TLS untuk nama domain khusus

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

catatan

Mutual TLS tidak didukung untuk pribadiAPIs.

Setelah Anda mengunggah truststore Anda ke Amazon S3, Anda dapat mengonfigurasi nama domain khusus Anda untuk digunakan bersama. TLS Tempelkan yang berikut (termasuk garis miring) ke terminal:

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 Anda membuat nama domain, Anda harus mengkonfigurasi DNS catatan 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 timbal balik TLS

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

Anda API dipanggil hanya jika truststore Anda mempercayai sertifikat. Kondisi berikut akan menyebabkan API Gateway gagal TLS jabat tangan dan menolak permintaan dengan kode 403 status. Jika sertifikat Anda:

• tidak dipercaya

• kedaluwarsa

• tidak menggunakan algoritme yang didukung

catatan

APIGateway 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 truststore Anda. Saat Anda memperbarui nama domain khusus untuk menggunakan versi truststore baru, API Gateway mengembalikan peringatan jika sertifikat tidak valid.

APIGateway menghasilkan peringatan sertifikat hanya ketika Anda memperbarui nama domain Anda. APIGateway tidak memberi tahu Anda jika sertifikat yang diunggah sebelumnya kedaluwarsa.

AWS CLI Perintah berikut memperbarui nama domain khusus 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 timbal balik TLS

Untuk menonaktifkan mutual TLS untuk nama domain kustom, hapus truststore dari nama domain kustom Anda, seperti yang ditunjukkan pada perintah berikut.

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

Memecahkan masalah timbal balik TLS untuk Anda REST API

Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat menyalakan timbal balik. TLS

Memecahkan masalah peringatan sertifikat

Saat membuat nama domain khusus dengan mutualTLS, 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 masih TLS diaktifkan untuk AndaAPI, tetapi beberapa klien mungkin tidak dapat mengakses AndaAPI.

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 TLS domain 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 AWS Support 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 dalamACM. 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 ACM terkelola pemecahan masalah.

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 bukan nama domain wildcard.

Perintah berikut menampilkan sertifikat mana yang dikembalikan oleh API Gateway:

openssl s_client -connect hostname:port

Jika sertifikat yang dihasilkan adalah untukFQDN, hubungi AWS Support untuk membuka tiket.