Mengonfigurasi TLS dari Edge ke backend (Cloud dan Private Cloud)

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

Proxy API berfungsi sebagai pemetaan endpoint yang tersedia secara publik ke layanan backend Anda. Host virtual menentukan cara proxy API yang ditampilkan kepada publik diekspos ke aplikasi. Misalnya, host virtual menentukan apakah proxy API dapat diakses menggunakan TLS. Saat mengonfigurasi proxy API, edit definisi ProxyEndpoint-nya untuk mengonfigurasi host virtual yang digunakannya.

TargetEndpoint adalah ekuivalen keluar dari ProxyEndpoint. TargetEndpoint berfungsi sebagai klien HTTP dari Edge ke layanan backend. Saat membuat proxy API, Anda dapat mengonfigurasinya agar menggunakan nol atau beberapa TargetEndpoints.

Pelajari lebih lanjut:

Mengonfigurasi TargetEndpoint atau TargetServer

Untuk mengonfigurasi TargetEndpoint, edit objek XML yang menentukan TargetEndpoint. Anda dapat mengedit TargetEndpoint dengan mengedit file XML yang menentukan TargetEndpoint di proxy API Anda, atau mengeditnya di UI pengelolaan Edge.

Untuk menggunakan UI pengelolaan Edge guna mengedit TargetEndpoint:

  1. Login ke UI pengelolaan Edge di https://enterprise.apigee.com.
  2. Pilih nama proxy API yang akan diupdate.
  3. Pilih tab Develop.
  4. Di bagian Target Endpoints, pilih default.
  5. Di area kode, definisi TargetEndpoint akan muncul, seperti di bawah ini:
    <TargetEndpoint name="default">
      <Description/>
      <FaultRules/>
      <Flows/>
      <PreFlow name="PreFlow">
        <Request/>
        <Response/>
      </PreFlow>
      <PostFlow name="PostFlow">
        <Request/>
        <Response/>
      </PostFlow>
      <HTTPTargetConnection>
        <Properties/>
        <SSLInfo>
          <Enabled>true</Enabled>
          <TrustStore>ref://myTrustStoreRef</TrustStore>
        </SSLInfo>
        <URL>https://mocktarget.apigee.net</URL>
      </HTTPTargetConnection>
    </TargetEndpoint>
  6. Konfigurasi truststore seperti yang dijelaskan di bawah di bagian Tentang konfigurasi TLS dengan backend.
  7. Buat perubahan dan simpan proxy. Jika proxy API telah di-deploy, simpan akan men-deploy ulang proxy tersebut dengan setelan baru.

Perhatikan bahwa definisi TargetEndpoint berisi properti name. Anda menggunakan nilai properti name untuk mengonfigurasi definisi ProxyEndpoint dari proxy API agar dapat menggunakan TargetEndpoint. Lihat referensi konfigurasi proxy API untuk mengetahui informasi selengkapnya.

TargetEndpoints dapat dikonfigurasi untuk mereferensikan TargetServer, bukan URL target eksplisit. Konfigurasi TargetServer memisahkan URL endpoint konkret dari konfigurasi TargetEndpoint. TargetServers digunakan untuk mendukung load balancing dan failover di beberapa instance server backend.

Di bawah ini adalah contoh definisi TargetServer:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer> 

TargetServer direferensikan menurut nama dalam elemen <HTTPTargetConnection> dalam definisi TargetEndpoint. Anda dapat mengonfigurasi satu atau beberapa TargetServers yang bernama, seperti yang ditunjukkan di bawah ini.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <LoadBalancer>
      <Server name="target1" />
      <Server name="target2" />
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

Lihat Load balancing di seluruh server backend untuk mengetahui informasi selengkapnya.

Tentang konfigurasi TLS dengan backend

Sebelum mengonfigurasi akses TLS ke backend, Anda harus memahami dua hal penting:

  1. Secara default, Edge tidak memvalidasi sertifikat backend. Anda harus membuat truststore untuk mengonfigurasi Edge guna memvalidasi sertifikat.
  2. Gunakan referensi untuk menentukan keystore atau truststore yang digunakan oleh Edge.

Kedua pertimbangan tersebut dijelaskan di bawah.

Menentukan truststore untuk mengaktifkan validasi sertifikat

Saat membuat permintaan TLS melalui TargetEndpoint atau TargetServer, Edge tidak secara default memvalidasi sertifikat TLS yang diterima dari server backend. Artinya, Edge tidak memvalidasi bahwa:

  • Sertifikat telah ditandatangani oleh CA terpercaya.
  • Sertifikat belum kedaluwarsa.
  • Sertifikat menampilkan nama yang umum. Jika ada nama umum, Edge tidak memvalidasi bahwa nama umum tersebut cocok dengan nama host yang ditentukan dalam URL.

Untuk mengonfigurasi Edge guna memvalidasi sertifikat backend, Anda harus:

  1. Membuat truststore di Edge.
  2. Upload sertifikat atau rantai sertifikat server ke truststore. Jika sertifikat server ditandatangani oleh pihak ketiga, Anda harus mengupload rantai sertifikat lengkap, termasuk sertifikat root CA, ke truststore. Tidak ada CA yang dipercaya secara implisit.
  3. Tambahkan truststore ke definisi TargetEndpoint atau TargetServer.

Lihat Keystore dan Truststore untuk mengetahui informasi selengkapnya.

Contoh:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Menggunakan referensi ke keystore atau truststore

Contoh di bawah ini menunjukkan cara mengonfigurasi TargetEndpoint atau TargetServer agar mendukung TLS. Sebagai bagian dari konfigurasi TLS, tetapkan truststore dan keystore sebagai bagian dari definisi TargetEndpoint atau TargetServer.

Apigee sangat merekomendasikan agar Anda menggunakan referensi ke keystore dan truststore dalam definisi TargetEndpoints atau TargetServer. Keuntungan menggunakan referensi adalah Anda hanya perlu memperbarui referensi agar mengarah ke keystore atau truststore yang berbeda untuk memperbarui sertifikat TLS.

Referensi ke keystore dan truststore dalam definisi TargetEndpoints atau TargetServer berfungsi dengan cara yang sama seperti untuk host virtual.

Mengonversi TargetEndpoint atau TargetServer untuk menggunakan referensi

Anda mungkin sudah memiliki definisi TargetEndpoint atau TargetServer yang menggunakan nama literal keystore dan truststore. Untuk mengonversi definisi TargetEndpoint atau TargetServer agar menggunakan referensi:

  1. Perbarui definisi TargetEndpoint atau TargetServer untuk menggunakan referensi.
  2. Mulai ulang Prosesor Pesan Edge:
    • Untuk pelanggan Cloud Publik, hubungi Dukungan Apigee Edge untuk memulai ulang Prosesor Pesan.
    • Untuk pelanggan Private Cloud, mulai ulang Prosesor Pesan Edge satu per satu.
  3. Pastikan TargetEndpoint atau TargetServer Anda berfungsi dengan benar.

Mengonfigurasi TLS satu arah ke server backend

Saat menggunakan definisi TargetEndpoint, mengonfigurasi akses TLS satu arah dari Edge (klien TLS) ke server backend (server TLS) tidak memerlukan konfigurasi tambahan di Edge. Server backend bebas mengonfigurasi TLS dengan benar.

Anda hanya perlu memastikan bahwa elemen <URL> dalam definisi TargetEndpoint mereferensikan layanan backend dengan protokol HTTPS dan bahwa Anda mengaktifkan TLS:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Jika Anda menggunakan TargetServer untuk menentukan layanan backend, aktifkan TLS dalam definisi TargetServer:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
  </SSLInfo> 
</TargetServer> 

Namun, jika ingin Edge memvalidasi sertifikat backend, Anda harus membuat truststore yang berisi sertifikat backend atau rantai sertifikat. Selanjutnya, Anda menentukan truststore dalam definisi TargetEndpoint:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

Atau dalam definisi TargetServer:

<TargetServer name="target1">
  <Host>mockserver.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
    <TrustStore>ref://myTrustStoreRef</TrustStore>
  </SSLInfo> 
</TargetServer>

Untuk mengonfigurasi TLS satu arah:

  1. Jika Anda ingin memvalidasi sertifikat backend, buat truststore di Edge, lalu upload sertifikat backend atau rantai CA, seperti yang dijelaskan di Keystore dan Truststore. Untuk contoh ini, jika Anda harus membuat truststore, beri nama myTrustStore.
  2. Jika Anda membuat truststore, gunakan panggilan POST API berikut untuk membuat referensi dengan nama myTrustStoreRef ke truststore yang Anda buat di atas:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
      -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
      </ResourceReference>' -u email:password
    
  3. Gunakan UI pengelolaan Edge untuk memperbarui definisi TargetEndpoint untuk proxy API (atau, jika Anda menentukan proxy API dalam XML, edit file XML untuk proxy):
    1. Login ke UI pengelolaan Edge di https://enterprise.apigee.com.
    2. Di menu UI pengelolaan Edge, pilih API.
    3. Pilih nama proxy API yang akan diupdate.
    4. Pilih tab Development.
    5. Di bagian Target Endpoints, pilih default.
    6. Di area kode, edit elemen <HTTPTargetConnection> untuk menambahkan elemen <SSLInfo>. Pastikan untuk menentukan referensi truststore yang benar dan menetapkan <Enabled> ke benar (true):
      <TargetEndpoint name="default">
        …
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        …
      </TargetEndpoint>
    7. Simpan proxy API. Jika proxy API telah di-deploy, simpan akan men-deploy ulang proxy tersebut dengan setelan baru.

Mengonfigurasi TLS dua arah ke server backend

Jika Anda ingin mendukung TLS dua arah antara Edge (klien TLS) dan server backend (server TLS):

  • Buat keystore di Edge lalu upload sertifikat Edge dan kunci pribadi.
  • Jika Anda ingin memvalidasi sertifikat backend, buat truststore di Edge yang berisi sertifikat dan rantai CA yang Anda terima dari server backend.
  • Perbarui TargetEndpoint dari semua proxy API yang merujuk server backend untuk mengonfigurasi akses TLS.

Menggunakan alias kunci untuk menentukan sertifikat keystore

Anda dapat menentukan beberapa sertifikat, masing-masing dengan aliasnya sendiri, di keystore yang sama. Secara default, Edge menggunakan sertifikat pertama yang didefinisikan dalam keystore.

Secara opsional, Anda dapat mengonfigurasi Edge untuk menggunakan sertifikat yang ditentukan oleh properti <KeyAlias>. Hal ini memungkinkan Anda menentukan satu keystore untuk beberapa sertifikat, lalu memilih yang ingin digunakan dalam definisi TargetServer. Jika Edge tidak dapat menemukan sertifikat dengan alias yang cocok dengan <KeyAlias>, Edge akan menggunakan tindakan default, yaitu memilih sertifikat pertama dalam keystore.

Edge untuk pengguna Cloud Publik harus menghubungi Dukungan Apigee Edge untuk mengaktifkan fitur ini.

Mengonfigurasi TLS dua arah

Untuk mengonfigurasi TLS dua arah:

  1. Buat keystore di Edge, lalu upload sertifikat dan kunci pribadi menggunakan prosedur yang dijelaskan di sini: Keystore dan Truststore. Untuk contoh ini, buat keystore bernama myTestKeystore yang menggunakan nama alias myKey untuk sertifikat dan kunci pribadi.
  2. Gunakan panggilan POST API berikut untuk membuat referensi bernama myKeyStoreRef ke keystore yang Anda buat di atas:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myKeyStoreRef">
        <Refers>myTestKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    

    Referensi tersebut menetapkan nama keystore dan jenis referensi sebagai KeyStore.

    Gunakan panggilan GET API berikut untuk melihat referensi:

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/myKeyStoreRef /
    -u email:password
    
  3. Jika Anda ingin memvalidasi sertifikat backend, buat truststore di Edge, lalu upload sertifikat dan rantai CA, seperti yang dijelaskan di sini: Keystore dan Truststore. Untuk contoh ini, jika Anda harus membuat nama truststore, yaitu myTrustStore.
  4. Jika Anda membuat truststore, gunakan panggilan POST API berikut untuk membuat referensi dengan nama myTrustStoreRef ke truststore yang Anda buat di atas:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    
  5. Gunakan UI pengelolaan Edge untuk memperbarui definisi TargetEndpoint untuk proxy API (atau, jika Anda menentukan proxy API dalam XML, edit file XML untuk proxy):
    1. Login ke UI pengelolaan Edge di https://enterprise.apigee.com.
    2. Di menu UI pengelolaan Edge, pilih API.
    3. Pilih nama proxy API yang akan diupdate.
    4. Pilih tab Development.
    5. Di bagian Target Endpoints, pilih default.
    6. Di area kode, edit elemen <HTTPTargetConnection> untuk menambahkan elemen <SSLInfo>. Pastikan untuk menentukan keystore dan alias kunci yang benar, serta setel elemen <Enabled> dan <ClientAuthEnabled> ke true:
      <TargetEndpoint name="default">
        ...
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>true</ClientAuthEnabled>
            <KeyStore>ref://myKeyStoreRef</KeyStore>
            <KeyAlias>myKey</KeyAlias>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        ...
      </TargetEndpoint>
    7. Simpan proxy API. Jika proxy API telah di-deploy, simpan akan men-deploy ulang proxy tersebut dengan setelan baru.

Untuk informasi selengkapnya tentang opsi yang tersedia di <TargetEndpoint>, termasuk menggunakan variabel untuk menyediakan nilai <SSLInfo> TargetEndpoint, lihat Referensi konfigurasi proxy API.

Mengaktifkan SNI

Edge mendukung penggunaan Server Name Indication (SNI) dari Message Processors untuk menargetkan endpoint di Apigee Edge untuk Cloud dan untuk deployment Private Cloud.

Agar Edge untuk Private Cloud memiliki kompatibilitas mundur dengan backend target yang ada, Apigee menonaktifkan SNI secara default. Jika backend target Anda dikonfigurasi untuk mendukung SNI, Anda dapat mengaktifkan fitur ini. Lihat Menggunakan SNI dengan Edge untuk informasi selengkapnya.