Opsi untuk mengonfigurasi TLS

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Bagian ini menunjukkan cara mengonfigurasi TLS untuk traffic dari proxy ke target.

Versi TLS yang tidak didukung: Apigee tidak mendukung penggunaan TLS 1.0 atau TLS1.1. Jika Anda menggunakan protokol ini dalam konfigurasi endpoint target, endpoint target Apigee akan menampilkan error messaging.adaptors.http.flow.SslHandshakeFailed.

Tentang menetapkan opsi TLS di endpoint target atau server target

Target dapat diwakili oleh objek XML seperti di bawah ini:

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

Area konfigurasi endpoint target yang Anda ubah untuk mengonfigurasi TLS ditentukan oleh tag <SSLInfo>. Anda menggunakan tag <SSLInfo> yang sama untuk mengonfigurasi endpoint target atau server target.

Untuk mengetahui informasi tentang elemen turunan <SSLInfo>, lihat Konfigurasi TargetEndpoint TLS/SSL.

Tabel berikut menjelaskan elemen konfigurasi TLS yang digunakan oleh tag <SSLInfo>:

Elemen	Deskripsi
<Enabled>	Blok <SSLInfo> dapat digunakan untuk TLS/SSL satu arah dan dua arah. Jika disetel ke true, <Enabled> menentukan bahwa blok <SSLInfo> harus digunakan. Jika disetel ke false, blok <SSLInfo> akan diabaikan. Nilai default <Enabled> adalah true jika <URL> menentukan protokol HTTPS, dan false jika <URL> menentukan HTTP.
<Enforce>	Menerapkan SSL ketat antara Apigee dan backend target. Jika disetel ke true, koneksi akan gagal untuk target dengan sertifikat yang tidak valid, sertifikat yang masa berlakunya habis, sertifikat yang ditandatangani sendiri, sertifikat dengan ketidakcocokan nama host, dan sertifikat dengan root yang tidak tepercaya. Kode kegagalan 4xx atau 5xx ditampilkan. Jika tidak disetel, atau disetel ke false, hasil koneksi ke backend target dengan sertifikat bermasalah bergantung pada setelan <IgnoreValidationErrors> (lihat di bawah). Respons berhasil (2xx) dapat terjadi dalam kondisi tertentu, jika <IgnoreValidationErrors> disetel ke true.
<ClientAuthEnabled>	Mengaktifkan TLS dua arah (juga dikenal sebagai mutual TLS atau mTLS) antara Apigee dan klien API, atau antara Apigee dan backend target. Mengaktifkan TLS dua arah biasanya mengharuskan Anda menyiapkan truststore di Apigee dan truststore.
<KeyStore>	Keystore yang berisi kunci pribadi yang digunakan untuk autentikasi klien keluar
<KeyAlias>	Alias yang ditentukan saat Anda mengupload sertifikat dan kunci pribadi ke keystore.
<TrustStore>	Keystore yang berisi sertifikat server tepercaya.
<IgnoreValidationErrors>	Menunjukkan apakah error validasi diabaikan. Jika sistem backend menggunakan SNI dan menampilkan sertifikat dengan Nama Pembeda (DN) subjek yang tidak cocok dengan nama host, tidak ada cara untuk mengabaikan error dan koneksi akan gagal. Catatan: Jika <Enforce> ditetapkan ke true, nilai <IgnoreValidationErrors> akan diabaikan.
<Ciphers>	Cipher yang didukung untuk TLS/SSL keluar. Jika tidak ada sandi yang ditentukan, semua sandi yang tersedia untuk JVM akan diizinkan. Untuk membatasi sandi, tambahkan elemen berikut yang mencantumkan sandi yang didukung: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>
<Protocols>	Protokol yang didukung untuk TLS/SSL keluar. Jika tidak ada protokol yang ditentukan, semua protokol yang tersedia untuk JVM akan diizinkan. Untuk membatasi protokol, tentukan protokol secara eksplisit. Misalnya, untuk hanya mengizinkan TLS v1.2 atau TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>

Tentang menyetel elemen <KeyStore> dan <TrustStore>

Pada contoh di atas, keystore dan truststore ditentukan menggunakan referensi, dalam bentuk:

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

Peringatan: Apigee sangat menyarankan agar Anda selalu menggunakan referensi ke keystore dan truststore. Referensi adalah variabel yang berisi nama keystore atau truststore, bukan menentukan nama keystore secara langsung. Jika Anda mengupload sertifikat baru yang tidak menggunakan referensi, tetapi menentukan nama keystore secara langsung, Pemroses Pesan runtime tidak akan otomatis mendeteksi perubahan tersebut. Untuk mengatasinya, Anda harus menghubungi Dukungan Google Cloud untuk memulai ulang Pemroses Pesan, yang dapat menyebabkan penurunan kualitas layanan sementara.

Dalam contoh ini:

• myKeystoreRef adalah referensi yang berisi nama keystore. Dalam contoh ini, nama keystore adalah myKeystore.
• myTruststoreRef adalah referensi yang berisi nama truststore. Dalam contoh ini, nama truststore adalah myTruststore.

Saat masa berlaku sertifikat habis, Anda harus mengupdate endpoint target/server target untuk menentukan keystore atau truststore yang berisi sertifikat baru. Namun, jika Anda menggunakan referensi, Anda dapat mengubah nilai references untuk mencerminkan nama keystore atau truststore baru, bukan mengubah endpoint target/server target. Mengubah nilai referensi tidak mengharuskan Anda menghubungi Layanan Pelanggan Google Cloud.

Atau, Anda dapat menentukan nama keystore dan nama truststore secara langsung:

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore>

Jika Anda secara langsung menentukan nama keystore atau truststore, Anda harus menghubungi Google Cloud Customer Care.

Opsi ketiga adalah menggunakan variabel alur:

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore>

Anda dapat menggunakan variabel alur untuk menentukan keystore atau truststore secara dinamis, dengan efek yang serupa dengan menggunakan referensi. Untuk mengetahui informasi selengkapnya, lihat Menggunakan variabel alur untuk menetapkan nilai TLS/SSL secara dinamis.

Tentang mengonfigurasi TLS

Semua pelanggan Apigee, baik yang berbayar maupun evaluasi, memiliki kontrol penuh atas konfigurasi endpoint target/server target. Selain itu, pelanggan Apigee berbayar memiliki kontrol penuh atas properti TLS.

Menangani sertifikat yang sudah tidak berlaku

Jika masa berlaku sertifikat TLS berakhir, atau jika konfigurasi sistem Anda berubah sehingga sertifikat tidak lagi valid, Anda harus memperbarui sertifikat. Saat mengonfigurasi TLS untuk endpoint target/server target, Anda harus memutuskan cara melakukan pembaruan tersebut sebelum melakukan konfigurasi apa pun.

Catatan: Anda tidak dapat memperbarui keystore atau truststore yang ada untuk menambahkan sertifikat baru. Anda harus membuat keystore/truststore baru saat memperbarui sertifikat. Biasanya, Anda membuat keystore/truststore baru dan mengupload sertifikat baru sebelum sertifikat di keystore/truststore lama berakhir. Hal ini memungkinkan Anda menguji keystore/truststore baru dan melakukan rollback ke keystore/truststore lama jika ada masalah.

Saat sertifikat berakhir

Di Apigee, Anda menyimpan sertifikat di salah satu dari dua tempat:

• Keystore - Berisi sertifikat TLS dan kunci pribadi yang digunakan untuk mengidentifikasi entitas selama TLS handshake.
• Truststore - Berisi sertifikat tepercaya di klien TLS yang digunakan untuk memvalidasi sertifikat server TLS yang diberikan kepada klien. Sertifikat ini biasanya berupa sertifikat yang ditandatangani sendiri, sertifikat yang ditandatangani oleh CA tepercaya, atau sertifikat yang digunakan sebagai bagian dari TLS dua arah (juga dikenal sebagai mutual TLS atau mTLS).

Metode yang Anda gunakan untuk menentukan keystore dan truststore di endpoint target atau server target akan menentukan cara Anda melakukan pembaruan sertifikat. Anda dapat menggunakan referensi, nama langsung, atau variabel alur. Setiap metode memiliki dampak yang berbeda pada proses update, seperti yang dijelaskan dalam tabel berikut:

Jenis konfigurasi	Cara memperbarui/mengganti sertifikat	Penggunaan / Dampak
Referensi (Direkomendasikan)	Keystore: Buat keystore baru dengan nama baru dan alias dengan nama yang sama dengan alias lama. Truststore: Buat truststore dengan nama baru. Nama alias tidak penting. Catatan: Jika sertifikat adalah bagian dari rantai, Anda harus membuat satu file yang berisi semua sertifikat dan mengupload file tersebut ke satu alias, atau mengupload semua sertifikat dalam rantai secara terpisah ke truststore menggunakan alias yang berbeda untuk setiap sertifikat.	Perbarui referensi untuk mengarah ke toko baru. Tidak perlu menghubungi Dukungan Apigee. Tanpa periode nonaktif.
Variabel alur	Keystore: Buat keystore baru dengan nama baru dan alias dengan nama yang sama atau baru. Truststore: Buat truststore dengan nama baru.	Teruskan variabel alur yang diperbarui pada setiap permintaan dengan nama toko baru. Tidak perlu menghubungi Dukungan Apigee. Tanpa periode nonaktif.
Langsung	Metode 1: Membuat toko baru (Direkomendasikan untuk menghindari periode nonaktif) Buat keystore atau truststore baru dengan nama baru dan upload sertifikat baru (dan kunci pribadi jika membuat keystore).	Perbarui konfigurasi endpoint target atau server target untuk menentukan nama toko baru secara langsung, lalu deploy ulang proxy API. Tidak perlu menghubungi Dukungan Apigee.
Langsung	Metode 2a: Update di tempat (Hapus & Buat Ulang) Hapus keystore atau truststore, lalu buat ulang dengan nama yang sama.	Permintaan API akan gagal selama periode penghapusan dan pembuatan ulang. Karena Message Processor menyimpan cache toko yang ditentukan secara langsung, Message Processor tidak akan otomatis mendeteksi sertifikat yang diperbarui. Anda harus menghubungi Customer Care Google Cloud untuk memulai ulang Pemroses Pesan.
Langsung	Metode 2b: Update di tempat (Upload Truststore) Untuk truststore saja, upload sertifikat baru langsung ke truststore yang ada.	Karena Message Processor menyimpan cache toko yang ditentukan secara langsung, Message Processor tidak akan otomatis mendeteksi sertifikat baru. Anda harus menghubungi Customer Care Google Cloud untuk memulai ulang Pemroses Pesan.