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 Router Edge untuk mengonfigurasi TLS.
  2. Akses ke layanan backend Anda oleh Edge. Gunakan endpoint target dan server target di Edge Message Processor untuk mengonfigurasi TLS.

Kedua jenis akses ini ditampilkan di bawah ini:

Tentang menyetel opsi TLS di host virtual atau target endpoint/server 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>. Anda menggunakan 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 endpoint/server target target, jika sistem backend menggunakan SNI dan menampilkan sertifikat dengan Nama yang Dibedakan (DN) subjek yang tidak cocok dengan nama host, error tersebut tidak akan dapat diabaikan dan koneksi akan gagal.

<CommonName>

Jika ditentukan, nilai yang menjadi dasar validasi nama umum sertifikat target. Nilai ini hanya valid untuk konfigurasi TargetEndpoint dan TargetServer. Ini tidak valid untuk konfigurasi VirtualHost.

Secara default, nilai yang ditentukan sama persis dengan nama umum sertifikat target. Misalnya, menggunakan *.myhost.com sebagai nilai untuk <CommonName> hanya akan cocok dan memvalidasi nama host target jika nilai persisnya *.myhost.com ditetapkan sebagai nama umum dalam sertifikat target.

Secara opsional, Apigee dapat melakukan pencocokan dengan karakter pengganti menggunakan atribut wildcardMatch.

Contohnya, nama umum yang ditentukan sebagai abc.myhost.com dalam sertifikat target akan dicocokkan dan divalidasi jika elemen <CommonName> ditentukan sebagai berikut:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

Tentang menetapkan elemen <KeyStore> dan <TrustStore>

Dalam contoh host virtual di atas, keystore dan truststore ditentukan menggunakan references, dalam bentuk:

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

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. 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 mengupdate host virtual atau server target/endpoint 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 memodifikasi host virtual atau endpoint/server target target itu sendiri:

  • Untuk pelanggan Cloud: Anda tidak perlu menghubungi Dukungan Apigee Edge untuk mengubah nilai referensi.
  • Untuk pelanggan Private Cloud: Anda tidak perlu memulai ulang komponen Edge, seperti Router dan Pemroses Pesan 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, 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/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 pembatasan berikut saat menggunakan referensi ke keystore dan truststore:

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

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

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

  1. Edge untuk Cloud

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

  2. Edge untuk Private Cloud

    Untuk mengonversi host virtual agar menggunakan referensi:

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

Tentang penggunaan sertifikat dan kunci 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 kunci dan sertifikat 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 ditunjukkan 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, serta menetapkan semua properti pada host virtual.

Semua pelanggan Cloud, baik yang berbayar maupun yang dievaluasi, 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 habis masa berlakunya

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

Kapan masa berlaku sertifikat habis

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

  • Keystore - Berisi sertifikat TLS dan kunci pribadi yang digunakan untuk mengidentifikasi entity 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 untuk 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 untuk menggunakan keystore baru.

Jika sertifikat di truststore berakhir, dan Anda menggunakan referensi ke truststore, Anda:

  1. Membuat truststore baru.
  2. Upload sertifikat baru ke truststore baru. Nama alias tidak masalah 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 server/endpoint target target untuk menggunakan truststore baru.

Ringkasan metode memperbarui sertifikat yang habis masa berlakunya

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

  • Referensi
  • Nama langsung
  • Variabel alur

Setiap metode ini memiliki dampak yang berbeda terhadap proses update, seperti yang dijelaskan dalam tabel berikut. Seperti yang Anda lihat, referensi memberikan fleksibilitas terbaik 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 seperti alias lama.

Untuk truststore, buat truststore dengan nama baru.

Perbarui referensi ke keystore atau truststore.

Tidak perlu memulai ulang Router atau Pemroses Pesan.

Perbarui referensi ke keystore atau truststore.

Tidak perlu menghubungi Dukungan Apigee.

Vars flow (khusus endpoint target) Untuk keystore, buat keystore baru dengan nama baru dan alias dengan nama yang sama atau nama baru.

Untuk truststore, buat truststore dengan nama baru.

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

Tidak perlu memulai ulang Router atau Pemroses Pesan.

Teruskan var alur yang diperbarui 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 target/endpoint target, deploy ulang proxy.

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

Jika truststore digunakan oleh server target/endpoint 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 Pemroses Pesan.

Update host virtual tidak diperlukan. 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 Pemroses Pesan.

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

Jika truststore digunakan oleh server target/endpoint target, mulai ulang Pemroses Pesan.

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

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