Opsi untuk mengonfigurasi TLS

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Dokumen ini berisi ringkasan cara Anda mengonfigurasi TLS di Edge untuk dua area fungsional:

  1. Akses ke proxy API Anda melalui klien API. Gunakan host virtual di Edge Router untuk mengonfigurasi TLS.
  2. Akses ke layanan backend Anda dengan Edge. Gunakan endpoint target dan server target di Edge Message Processor untuk mengonfigurasi TLS.

Kedua jenis akses ini ditampilkan di bawah ini:

Tentang setelan opsi TLS di host virtual atau server endpoint/target target

Host virtual dapat diwakili oleh objek XML, dalam bentuk:

<VirtualHost name="secure">
    ...
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTruststoreRef</TrustStore> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

Area host virtual yang Anda ubah untuk mengonfigurasi TLS ditentukan oleh tag <SSLInfo>. Gunakan tag <SSLInfo> yang sama untuk mengonfigurasi endpoint target atau server target.

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

Elemen Deskripsi
<Diaktifkan>

Mengaktifkan TLS satu arah antara Edge dan klien API, atau antara Edge dan backend target.

Untuk host virtual, Anda harus menentukan keystore yang berisi sertifikat dan kunci pribadi.

<ClientAuthEnabled>

Mengaktifkan TLS dua arah antara Edge dan klien API, atau antara Edge dan backend target.

Mengaktifkan TLS dua arah biasanya mengharuskan Anda menyiapkan truststore di Edge.

<KeyStore> Keystore.
<KeyAlias> Alias yang ditentukan saat Anda mengupload sertifikat dan kunci pribadi ke keystore.
<TrustStore> Truststore.
<IgnoreValidationErrors>

Jika true (benar), Edge akan mengabaikan error sertifikat TLS. Berlaku saat mengonfigurasi TLS untuk server target dan endpoint target, serta saat mengonfigurasi host virtual yang menggunakan TLS 2 arah. Nilai defaultnya adalah false.

Saat digunakan dengan server target/endpoint target, jika sistem backend menggunakan SNI dan menampilkan sertifikat dengan subject Distinguished Name (DN) yang tidak cocok dengan nama host, error tersebut tidak dapat diabaikan dan koneksi akan gagal.

Tentang menetapkan elemen <KeyStore> dan <TrustStore>

Pada contoh host virtual di atas, keystore dan truststore ditentukan menggunakan references, 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.

Jika masa berlaku sertifikat berakhir, Anda harus mengupdate host virtual atau server endpoint/target target untuk menentukan keystore atau truststore yang berisi sertifikat baru. Keuntungan menggunakan referensi adalah Anda dapat memodifikasi nilai referensi untuk mengubah keystore atau truststore tanpa harus mengubah host virtual atau target endpoint/server target itu sendiri:

  • Untuk pelanggan Cloud: Jika nilai referensi diubah, Anda tidak perlu menghubungi Dukungan Apigee Edge.
  • Untuk pelanggan Private Cloud: Mengubah nilai referensi tidak mengharuskan Anda memulai ulang komponen Edge, seperti Router dan Pemroses Pesan.

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

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

Jika Anda menentukan nama keystore atau truststore secara langsung, pelanggan Cloud harus menghubungi Dukungan Apigee Edge dan pelanggan Private Cloud harus memulai ulang komponen Edge tertentu untuk memperbarui sertifikat.

Opsi ketiga, khusus untuk endpoint target/server target, adalah menggunakan variabel alur:

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

Variabel alur berfungsi untuk endpoint/server target target dan memungkinkan Anda mengupdate keystore atau truststore seperti referensi. Namun, metode ini tidak berfungsi dengan host virtual, dan mengharuskan Anda meneruskan informasi tentang keystore, alias, dan truststore pada setiap permintaan.

Pembatasan dalam penggunaan referensi untuk keystore dan truststore

Pelanggan Cloud berbayar dan semua pelanggan Private Cloud yang mengonfigurasi TLS harus mempertimbangkan batasan berikut saat menggunakan referensi ke keystore dan truststore:

  • Anda hanya dapat menggunakan referensi keystore dan truststore di host virtual jika menghentikan TLS di Router Apigee.
  • Jika Anda memiliki load balancer di depan Router Apigee, dan menghentikan TLS pada load balancer, Anda tidak dapat menggunakan referensi keystore dan truststore di host virtual.

Jika host virtual Anda yang ada menggunakan keystore atau nama truststore literal

Host virtual yang ada di Edge mungkin tidak dikonfigurasi untuk menggunakan referensi untuk keystore dan truststore. Dalam hal ini, Anda dapat mengupdate host virtual untuk menggunakan referensi.

  1. Edge untuk Cloud

    Untuk mengubah host virtual agar menggunakan referensi ke keystore, Anda harus menggunakan Dukungan Apigee Edge.

  2. Edge untuk Private Cloud

    Untuk mengonversi host virtual agar menggunakan referensi:

    1. Mengupdate host virtual untuk menggunakan referensi.
    2. Mulai ulang Router.
    Lihat "Mengubah host virtual untuk menggunakan referensi ke keystore dan truststore" di Mengonfigurasi akses TLS ke API untuk Private Cloud untuk mengetahui informasi selengkapnya.

Tentang penggunaan kunci dan sertifikat uji coba gratis Apigee

Jika memiliki akun Edge untuk Cloud berbayar dan belum memiliki sertifikat dan kunci TLS, Anda dapat membuat host virtual yang menggunakan sertifikat dan kunci uji coba gratis Apigee. Artinya, Anda dapat membuat host virtual tanpa membuat keystore terlebih dahulu.

Objek XML yang menentukan host virtual menggunakan kunci dan sertifikat uji coba gratis Apigee menghilangkan elemen <KeyStore> dan <KeyAlias>, serta menggantinya dengan elemen <UseBuiltInFreeTrialCert>, seperti yang ditampilkan di bawah ini:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

Jika melakukan TLS dua arah, Anda tetap harus menetapkan elemen <ClientAuthEnabled> ke true, dan menentukan truststore menggunakan referensi dengan elemen <TrustStore>.

Lihat Mengonfigurasi host virtual untuk Cloud guna mengetahui informasi selengkapnya.

Tentang mengonfigurasi TLS

Dua faktor utama menentukan cara Anda melakukan konfigurasi TLS:

  • Apakah Anda pelanggan Edge Cloud atau Private Cloud?
  • Bagaimana cara memperbarui sertifikat yang telah habis masa berlakunya atau akan habis masa berlakunya?

Opsi konfigurasi Cloud dan Private Cloud

Tabel berikut menunjukkan berbagai opsi konfigurasi untuk pelanggan Cloud dan Private Cloud:

Private Cloud Cloud
Host virtual Kontrol penuh Kontrol penuh hanya untuk akun berbayar
Endpoint target/server target Kontrol penuh Kontrol penuh

Pelanggan Private Cloud memiliki kontrol penuh atas konfigurasi host virtual dan endpoint/server target target. Kontrol tersebut mencakup kemampuan untuk membuat dan menghapus host virtual, dan menetapkan semua properti pada host virtual.

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

Menangani sertifikat yang sudah tidak berlaku

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

Kapan masa berlaku sertifikat berakhir

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

  • Keystore - Berisi sertifikat TLS dan kunci pribadi yang digunakan untuk mengidentifikasi entitas selama handshake TLS.
  • Truststore - Berisi sertifikat tepercaya pada 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.

Jika sertifikat dalam keystore sudah tidak berlaku 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 host virtual atau endpoint server/target target agar dapat menggunakan keystore baru.

Saat sertifikat di truststore habis masa berlakunya, dan Anda menggunakan referensi ke truststore, Anda:

  1. Membuat 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 tersebut secara terpisah ke truststore menggunakan alias yang berbeda untuk setiap sertifikat.
  3. Perbarui referensi di host virtual atau endpoint server/target target untuk menggunakan truststore baru.

Ringkasan metode memperbarui sertifikat yang habis masa berlakunya

Metode yang Anda gunakan untuk menetapkan nama keystore dan truststore di host virtual atau target endpoint/server target akan menentukan cara Anda menjalankan update sertifikat. Anda dapat menggunakan:

  • Referensi
  • Nama langsung
  • Variabel alur

Tiap metode ini memiliki dampak yang berbeda terhadap proses update, seperti yang dijelaskan dalam tabel berikut. Seperti yang Anda lihat, referensi memberikan fleksibilitas terbesar bagi pelanggan Cloud dan Private Cloud:

Jenis konfigurasi Cara memperbarui/mengganti sertifikat Private Cloud Cloud
Referensi (Direkomendasikan) Untuk keystore, buat keystore baru dengan nama baru dan alias dengan nama yang sama dengan alias lama.

Untuk truststore, buat truststore dengan nama baru.

Perbarui referensi ke keystore atau truststore.

Tidak perlu memulai ulang Router atau Prosesor Pesan.

Perbarui referensi ke keystore atau truststore.

Tidak perlu menghubungi Dukungan Apigee.

Variabel alur (khusus endpoint target) 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 var alur yang diupdate pada setiap permintaan dengan nama keystore, alias, atau truststore baru.

Tidak perlu memulai ulang Router atau Prosesor Pesan.

Teruskan var alur yang diupdate pada setiap permintaan dengan nama keystore, alias, atau truststore baru.

Tidak perlu menghubungi Dukungan Apigee.

Langsung Buat keystore, alias, truststore baru. Update host virtual dan mulai ulang Router.

Jika truststore digunakan oleh server endpoint/target target, deploy ulang proxy.

Untuk host virtual, hubungi Dukungan Apigee Edge untuk memulai ulang Router.

Jika truststore digunakan oleh server endpoint/target target, deploy ulang proxy.

Langsung Hapus keystore atau truststore, lalu buat ulang dengan nama yang sama. Tidak perlu update host virtual, tidak perlu memulai ulang Router. Namun, permintaan API akan gagal hingga keystore dan alias baru ditetapkan.

Jika keystore digunakan untuk TLS dua arah antara Edge dan layanan backend, mulai ulang Prosesor Pesan.

Tidak diperlukan update host virtual. Namun, permintaan API akan gagal hingga keystore dan alias baru ditetapkan.

Jika keystore digunakan untuk TLS dua arah antara Edge dan layanan backend, hubungi Dukungan Apigee Edge untuk memulai ulang Prosesor Pesan.

Langsung Khusus untuk truststore, upload sertifikat baru ke truststore. Jika truststore digunakan oleh host virtual, mulai ulang Router.

Jika truststore digunakan oleh server endpoint/target target, mulai ulang Message Pemrosess.

Untuk host virtual, hubungi Dukungan Apigee Edge untuk memulai ulang Router Edge.

Jika truststore digunakan oleh server endpoint/target target, hubungi Dukungan Apigee Edge untuk memulai ulang Message Processors.