Mengonfigurasi akses TLS ke API untuk Private Cloud

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

Host virtual di Edge menentukan domain dan port tempat proxy API diekspos, dan juga URL yang digunakan aplikasi untuk mengakses proxy API.

Host virtual juga menentukan apakah proxy API diakses menggunakan protokol HTTP, atau oleh protokol HTTPS terenkripsi yang menggunakan TLS. Saat mengonfigurasi host virtual untuk menggunakan HTTPS dan TLS, Anda harus membuat host virtual di Edge dan mengonfigurasi host virtual untuk menggunakan keystore dan truststore.

Pelajari lebih lanjut:

Yang Anda perlukan untuk membuat {i>host<i} virtual

Sebelum membuat host virtual, Anda harus memiliki informasi berikut:

  • Nama domain host virtual yang dapat dilihat publik. Misalnya, Anda harus mengetahui apakah nama yang dapat dilihat publik adalah api.myCompany.com, myapi.myCompany.com, dll. Informasi tersebut digunakan saat Anda membuat host virtual dan juga saat Anda membuat data DNS untuk host virtual.
  • Untuk TLS satu arah, Anda perlu membuat keystore dengan keystore yang berisi hal-hal berikut:
    • Sertifikat TLS - baik sertifikat yang ditandatangani oleh certificate authority (CA), maupun rantai sertifikat tempat sertifikat terakhir ditandatangani oleh CA.
    • Kunci pribadi - Edge mendukung ukuran kunci hingga 2048 bit. Frasa sandi bersifat opsional.
  • Untuk TLS dua arah, Anda memerlukan keystore dan memerlukan truststore untuk menyimpan sertifikat klien dan, secara opsional, rantai CA sertifikat. Anda memerlukan truststore meskipun sertifikat ditandatangani oleh CA.

Lihat Keystore dan Truststore untuk informasi selengkapnya tentang cara membuat keystore dan truststore.

Konfigurasi host virtual untuk TLS

Untuk membuat host virtual, buat objek XML yang mendefinisikan host virtual. Objek XML berikut menggunakan elemen <SSLInfo> untuk menentukan host virtual bagi konfigurasi TLS satu arah melalui HTTPS:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Dalam contoh ini, elemen <Enabled> disetel ke benar (true) untuk mengaktifkan TLS satu arah, dan elemen <KeyStore> serta <KeyAlias> menentukan keystore dan kunci yang digunakan oleh koneksi TLS.

Untuk mengaktifkan TLS dua arah, tetapkan elemen <ClientAuthEnabled> ke true, dan tentukan truststore menggunakan elemen <TrustStore>. Truststore menyimpan sertifikat klien dan, secara opsional, rantai CA sertifikat.

Menentukan cara menentukan nama keystore dan truststore di host virtual

Pada contoh host virtual di atas, Anda menentukan keystore dengan menggunakan referensi. Referensi adalah variabel yang berisi nama keystore, bukan menentukan nama keystore secara langsung.

Keuntungan menggunakan referensi adalah Anda dapat mengubah nilai referensi untuk mengubah keystore yang digunakan oleh host virtual, biasanya karena masa berlaku sertifikat dalam keystore saat ini akan berakhir dalam waktu dekat. Mengubah nilai referensi tidak mengharuskan Anda memulai ulang Router Edge.

Atau, Anda dapat menggunakan nama keystore literal di host virtual. Namun, jika Anda pernah memodifikasi host virtual untuk mengubah nama keystore, Anda harus memulai ulang Router Edge.

Pembatasan dalam penggunaan referensi untuk keystore dan truststore

Anda harus mempertimbangkan batasan berikut saat menggunakan referensi ke keystore dan truststore:

  • Anda hanya dapat menggunakan referensi keystore dan truststore di host virtual jika Anda mendukung SNI dan menghentikan SSL 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.

Memodifikasi host virtual yang ada untuk menggunakan referensi ke keystore dan truststore

Apigee sangat merekomendasikan agar host virtual menggunakan referensi ke keystore dan truststore. Referensi memungkinkan Anda mengubah keystore dan truststore yang digunakan oleh host virtual tanpa harus memulai ulang Router Edge.

Jika host virtual Anda saat ini dikonfigurasi untuk menggunakan nama literal keystore atau truststore, Anda dapat mengonversinya agar menggunakan referensi. Untuk melakukannya, update host virtual agar menggunakan referensi, lalu mulai ulang Router Edge.

Menyetel cipher dan protokol TLS untuk Edge 4.15.07 dan yang lebih lama

Jika menggunakan Edge versi 4.15.07 dan yang lebih lama, Anda harus menetapkan protokol dan cipher TLS yang digunakan oleh host virtual menggunakan tag turunan <Ciphers> dan <Protocols> dari tag <SSLInfo>. Tag ini dijelaskan dalam tabel di bawah.

Contoh:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

Tag <Cipher> menggunakan nama Java dan JSSE dari cipher tersebut. Misalnya, untuk Java 8, lihat http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites.

Menentukan cipher dan protokol TLS untuk Edge 4.16.01 hingga 4.16.09

Di Edge 4.16.01 hingga 4.16.09, Anda menetapkan cipher dan protokol default untuk host virtual secara global di Router. Default ini kemudian berlaku untuk semua host virtual.

Gunakan token untuk menentukan protokol dan cipher default:

  • Untuk menentukan protokol default, gunakan token conf_load_balancing_load.balancing.driver.server.ssl.protocols
  • Untuk menentukan cipher default bagi Router, gunakan token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Nilai default token conf_load_balancing_load.balancing.driver.server.ssl.protocols adalah:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

Setelan ini menentukan bahwa Router mendukung TLS versi 1.0, 1.1, dan 1.2. Tentukan daftar nilai yang dipisahkan spasi ke token.

Nilai default token conf_load_balancing_load.balancing.driver.server.ssl.ciphers adalah:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

Setelan ini menentukan:

  • Diperlukan panjang kunci 128 bit atau lebih (HIGH).
  • Kecualikan cipher tanpa autentikasi (!aNULL)
  • Kecualikan cipher suite yang menggunakan MD5 (!MD5)
  • Kecualikan cipher suite yang menggunakan DH (termasuk DH anonim, DH efemeral, dan DH tetap) DAN tiga DES (!DH+3DES)
  • Kecualikan cipher suite menggunakan pertukaran kunci RSA DAN DES tiga (!RSA+3DES)

Untuk mengetahui informasi tentang sintaksis dan nilai yang diizinkan oleh token ini, lihat Cipher OpenSSL. Perlu diperhatikan bahwa token ini menggunakan nama cipher OpenSSL, seperti AES128-SHA256, dan bukan nama cipher Java/JSSE, seperti TLS_RSA_WITH_AES_128_CBC_SHA256.

Untuk menetapkan token untuk Router:

  1. Edit file /opt/apigee/customer/application/router.properties. Jika file tersebut tidak ada, buatlah file tersebut.
  2. Tetapkan token conf_load_balancing_load.balancing.driver.server.ssl.ciphers. Misalnya, untuk menentukan TLSv1.2 saja dan mengecualikan cipher suite menggunakan kunci yang dibagikan sebelumnya, tambahkan!PSK:
    conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
    conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK
  3. Pastikan file router.properties dimiliki oleh apigee:
    chown apigee:apigee /opt/apigee/customer/application/router.properties
  4. Mulai ulang Router Edge:
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  5. Periksa nilai token:
    /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Menyetel parameter virtual host TLS untuk Edge versi 4.17.01 dan yang lebih baru

Jika menggunakan Edge versi 4.17.01 dan yang lebih baru, Anda dapat menetapkan beberapa properti TLS untuk host virtual individual, seperti protokol dan cipher TLS, menggunakan tag turunan <Properties> dari tag <VirtualHost>. Tag ini dijelaskan dalam Referensi properti host virtual.

Contoh:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

Untuk mengetahui informasi tentang sintaksis dan nilai yang diizinkan oleh token ssl_ciphers, lihat Cipher OpenSSL. Perlu diketahui bahwa token ini menggunakan nama cipher OpenSSL, seperti AES128-SHA256, dan bukan nama cipher Java/JSSE, seperti TLS_RSA_WITH_AES_128_CBC_SHA256.

Membuat host virtual yang menggunakan HTTPS

Contoh ini menetapkan keystore ke host virtual dengan menggunakan referensi. Dengan menggunakan referensi, Anda dapat mengubah keystore tanpa harus memulai ulang Router.

Gunakan prosedur berikut untuk membuat host virtual:

  1. Buat dan konfigurasi keystore bernama myTestKeystore menggunakan prosedur yang dijelaskan di sini: Keystore dan Truststore. Pastikan keystore menggunakan nama alias myKeyAlias untuk sertifikat dan kunci pribadi.
  2. Gunakan panggilan POST API berikut untuk membuat referensi bernama keystoreref 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="keystoreref">
        <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/keystoreref -u uname:password
    
  3. Buat host virtual menggunakan Create a Virtual Host API, dengan <ms-IP> sebagai alamat IP atau nama domain node Server Pengelolaan.

    Pastikan untuk menetapkan referensi keystore dan alias kunci yang benar:

    curl -X POST -H "Content-Type:application/xml" \
      http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
      -d '<VirtualHost  name="newTLSTrustStore2">
        <HostAliases>
          <HostAlias>apiTLS.myCompany.com</HostAlias>
        </HostAliases>
        <Interfaces/>
        <Port>9005</Port>
        <OCSPStapling>off</OCSPStapling>
        <SSLInfo>
          <Enabled>true</Enabled>
          <ClientAuthEnabled>false</ClientAuthEnabled>
          <KeyStore>ref://keystoreref</KeyStore>
          <KeyAlias>myKeyAlias</KeyAlias>
        </SSLInfo>
      </VirtualHost>' \
      -u email:password
  4. Buat data DNS untuk host virtual yang cocok dengan alias host.
  5. Jika Anda sudah memiliki proxy API, tambahkan host virtual ke elemen <HTTPConnection> di ProxyEndpoint. Host virtual ditambahkan secara otomatis ke semua proxy API baru.

    Lihat Memperbarui proxy API setelah membuat host virtual di Tentang host virtual.

Setelah mengupdate proxy API untuk menggunakan host virtual dan membuat data DNS untuk alias host, Anda dapat mengakses proxy API seperti yang ditunjukkan di bawah ini:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

Contoh:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Membuat dan mengubah referensi ke keystore atau truststore

Secara opsional, Anda dapat mengonfigurasi host virtual agar menggunakan referensi ke keystore atau truststore. Keuntungan menggunakan referensi adalah Anda dapat memperbarui referensi agar mengarah ke keystore atau truststore lain untuk memperbarui sertifikat TLS tanpa harus memulai ulang Router.

Misalnya, yang ditampilkan di bawah ini adalah host virtual yang menggunakan referensi ke keystore:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Gunakan panggilan POST API berikut untuk membuat referensi bernama keystoreref:

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

Referensi tersebut menetapkan nama keystore dan jenisnya.

Gunakan panggilan GET API berikut untuk melihat referensi:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Untuk mengubah referensi nanti agar mengarah ke keystore yang berbeda, untuk memastikan bahwa alias tersebut memiliki nama yang sama, gunakan panggilan PUT berikut:

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