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.

Tentang menetapkan opsi TLS di endpoint target atau server target

Target dapat diwakili oleh objek XML seperti yang ada 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 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 ditetapkan ke true, <Enabled> akan menentukan bahwa blok <SSLInfo> harus digunakan. Jika ditetapkan 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 ditetapkan ke true, koneksi akan gagal untuk target dengan sertifikat yang tidak valid, sertifikat yang sudah tidak berlaku, sertifikat yang ditandatangani sendiri, sertifikat dengan nama host yang tidak cocok, dan sertifikat dengan root yang tidak tepercaya. Kode kegagalan 4xx atau 5xx akan ditampilkan. Jika tidak ditetapkan, atau ditetapkan ke false, hasil koneksi ke backend target dengan sertifikat yang bermasalah bergantung pada setelan <IgnoreValidationErrors> (lihat di bawah). Respons berhasil (2xx) dapat terjadi dalam kondisi tertentu, jika <IgnoreValidationErrors> ditetapkan ke true.
<ClientAuthEnabled>	Mengaktifkan TLS dua arah (juga dikenal sebagai TLS bersama 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 Distinguished Name (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 cipher yang ditentukan, semua cipher yang tersedia untuk JVM akan diizinkan. Untuk membatasi cipher, tambahkan elemen berikut yang mencantumkan cipher 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 secara eksplisit. Misalnya, untuk hanya mengizinkan TLS v1.2 atau TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>

Tentang menetapkan elemen <KeyStore> dan <TrustStore>

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

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

Apigee sangat merekomendasikan agar Anda selalu menggunakan referensi ke keystore dan truststore. Referensi adalah variabel yang berisi nama keystore atau truststore, bukan menentukan nama keystore secara langsung. 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 berakhir, Anda harus memperbarui endpoint target/server target untuk menentukan keystore atau truststore yang berisi sertifikat baru. Keuntungan referensi adalah Anda dapat mengubah nilai referensi untuk mengubah keystore atau truststore tanpa harus mengubah endpoint target/server target itu sendiri:

Anda tidak perlu menghubungi Layanan Pelanggan Google Cloud untuk mengubah nilai referensi.

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

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

Jika Anda menentukan nama keystore atau truststore secara langsung, Anda harus menghubungi Layanan Pelanggan Google Cloud.

Opsi ketiga adalah menggunakan variabel alur:

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

Fungsi variabel alur memungkinkan Anda memperbarui keystore atau truststore seperti referensi. Untuk mengetahui informasi selengkapnya, lihat Menggunakan variabel alur untuk menetapkan nilai TLS/SSL secara dinamis.

Tentang cara mengonfigurasi TLS

Semua pelanggan Apigee, baik 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 update 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 masa berlaku 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 masa berlaku sertifikat berakhir

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

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

Jika masa berlaku sertifikat di keystore berakhir, dan Anda menggunakan referensi ke keystore, Anda tidak dapat mengupload sertifikat baru ke keystore. Sebagai gantinya, Anda:

1. Buat keystore baru.
2. Upload sertifikat baru ke keystore baru menggunakan nama alias yang sama seperti di keystore lama.
3. Perbarui referensi di server target/endpoint target untuk menggunakan keystore baru.

Saat masa berlaku sertifikat di truststore berakhir, dan Anda menggunakan referensi ke truststore, Anda:

1. Buat truststore baru.
2. Upload sertifikat baru ke truststore baru. Nama alias tidak penting untuk truststore. 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.
3. Perbarui referensi di server target/endpoint target untuk menggunakan truststore baru.

Ringkasan metode untuk memperbarui sertifikat yang masa berlakunya telah berakhir

Metode yang Anda gunakan untuk menentukan nama keystore dan truststore di endpoint target/server target menentukan cara Anda melakukan update sertifikat. Anda dapat menggunakan:

• Referensi
• Nama langsung
• Variabel alur

Setiap metode ini memiliki konsekuensi yang berbeda pada proses update, seperti yang dijelaskan dalam tabel berikut:

Jenis konfigurasi	Cara memperbarui/mengganti sertifikat	Penggunaan
Referensi (Direkomendasikan)	Untuk keystore, buat keystore baru dengan nama baru dan alias dengan nama yang sama seperti alias lama. Untuk truststore, buat truststore dengan nama baru.	Perbarui referensi ke keystore atau truststore. Tidak perlu menghubungi Dukungan Apigee.
Variabel flow	Untuk keystore, buat keystore baru dengan nama baru dan alias dengan nama yang sama atau dengan nama baru. Untuk truststore, buat truststore dengan nama baru.	Teruskan variabel alur yang diperbarui pada setiap permintaan dengan nama keystore, alias, atau truststore baru. Tidak perlu menghubungi Dukungan Apigee.
Langsung	Buat keystore, alias, dan truststore baru.	Deploy ulang proxy.
Langsung	Hapus keystore atau truststore dan buat ulang dengan nama yang sama.	Permintaan API akan gagal hingga keystore dan alias baru ditetapkan. Jika keystore digunakan untuk TLS dua arah (juga dikenal sebagai TLS timbal balik atau mTLS) antara Apigee dan layanan backend, hubungi Layanan Pelanggan Google Cloud untuk memulai ulang Message Processor.
Langsung	Khusus untuk truststore, upload sertifikat baru ke truststore.	Hubungi Layanan Pelanggan Google Cloud untuk memulai ulang Pemroses Pesan.