Mengonfigurasi nama domain kustom untuk instans Azure API Management Anda

BERLAKU UNTUK: Semua tingkat API Management

Saat Anda membuat instans layanan Azure API Management di cloud Azure, Azure menetapkannya subdomain azure-api.net (misalnya, apim-service-name.azure-api.net). Anda juga dapat mengekspos titik akhir API Management menggunakan nama domain kustom Anda sendiri, seperti contoso.com. Artikel ini memperlihatkan kepada Anda cara memetakan nama DNS kustom yang ada ke titik akhir yang diekspos oleh instans API Management.

Penting

API Management hanya menerima permintaan dengan nilai header host yang cocok:

• Nama domain bawaan Gateway
• Salah satu nama domain kustom Gateway yang dikonfigurasi

Nota

Saat ini, nama domain kustom tidak didukung di gateway ruang kerja.

Penting

Perubahan pada infrastruktur layanan API Management Anda (seperti mengonfigurasi domain kustom, menambahkan sertifikat CA, penskalaan, konfigurasi jaringan virtual, perubahan zona ketersediaan, dan penambahan wilayah) dapat memakan waktu 15 menit atau lebih lama untuk diselesaikan, tergantung pada tingkat layanan dan ukuran penyebaran. Harapkan waktu yang lebih lama untuk instans dengan jumlah unit skala atau konfigurasi multi-wilayah yang lebih besar. Perubahan bergulir pada API Management dijalankan dengan hati-hati untuk mempertahankan kapasitas dan ketersediaan.

Saat layanan diperbarui, perubahan infrastruktur layanan lainnya tidak dapat dilakukan. Namun, Anda dapat mengonfigurasi API, produk, kebijakan, dan pengaturan pengguna. Layanan ini tidak akan mengalami waktu henti gateway, dan API Management akan terus melayani permintaan API tanpa gangguan (kecuali di tingkat Pengembang).

Prasyarat

• Instans Manajemen API. Untuk informasi selengkapnya, lihat Membuat instans Azure API Management.

• Nama domain kustom yang dimiliki oleh Anda atau organisasi Anda. Artikel ini tidak memberikan instruksi tentang cara mendapatkan nama domain kustom.

• Secara opsional, sertifikat yang valid dengan kunci publik dan privat (. PFX). Subjek atau nama alternatif subjek (SAN) harus cocok dengan nama domain (ini memungkinkan instans API Management mengekspos URL dengan aman melalui TLS).

  Lihat Opsi sertifikat domain.

• Catatan DNS yang dihosting di server DNS untuk memetakan nama domain kustom ke nama domain default instans API Management Anda. Topik ini tidak menyediakan instruksi tentang cara menghosting catatan DNS.

  Untuk informasi selengkapnya tentang rekaman yang diperlukan, lihat Konfigurasi DNS, nanti di artikel ini.

Titik akhir untuk domain kustom

Ada beberapa titik akhir API Management yang dapat Anda tetapkan nama domain kustomnya. Saat ini, titik akhir berikut tersedia:

Titik akhir	Bawaan
Gateway	Defaultnya adalah: <apim-service-name>.azure-api.net. Gateway adalah satu-satunya titik akhir yang tersedia untuk konfigurasi di tingkat Konsumsi. Konfigurasi titik akhir Gateway default tetap tersedia setelah domain Gateway kustom ditambahkan.
Portal pengembang (semua tingkatan kecuali Konsumsi)	Defaultnya adalah: <apim-service-name>.developer.azure-api.net
Manajemen (hanya tingkat klasik)	Defaultnya adalah: <apim-service-name>.management.azure-api.net
API konfigurasi gateway yang dihost sendiri (v2)	Defaultnya adalah: <apim-service-name>.configuration.azure-api.net
SCM (hanya tingkat klasik)	Defaultnya adalah: <apim-service-name>.scm.azure-api.net

Pertimbangan

• Anda dapat memperbarui salah satu titik akhir yang didukung di tingkat layanan Anda. Biasanya, pelanggan memperbarui Gateway (URL ini digunakan untuk memanggil API yang diekspos melalui API Management) dan portal Pengembang (URL portal pengembang).
• Titik akhir Gateway default tetap tersedia setelah Anda mengonfigurasi nama domain Gateway kustom dan tidak dapat dihapus. Untuk titik akhir API Management lainnya (seperti portal Pengembang) yang Anda konfigurasi dengan nama domain kustom, titik akhir default tidak lagi tersedia.
• Hanya pemilik instans API Management yang dapat menggunakan titik akhir Management dan SCM secara internal. Titik akhir ini lebih jarang diberi nama domain kustom.
• Tingkat Premium dan Pengembang mendukung pengaturan beberapa nama host untuk titik akhir Gateway .
• Nama domain wildcard, seperti *.contoso.com, didukung di semua tingkatan kecuali tingkat Konsumsi. Sertifikat subdomain tertentu (misalnya, api.contoso.com) akan mengambil keutamaan dibandingkan dengan sertifikat wildcard (*.contoso.com) untuk permintaan ke api.contoso.com.
• Saat mengonfigurasi domain kustom untuk portal Pengembang, Anda dapat mengaktifkan CORS untuk nama domain baru. Ini diperlukan bagi pengunjung portal pengembang untuk menggunakan konsol interaktif di halaman referensi API.

Opsi sertifikat domain

API Management mendukung sertifikat atau sertifikat TLS kustom yang diimpor dari Azure Key Vault. Anda juga dapat mengaktifkan sertifikat terkelola gratis.

Peringatan

Jika Anda memerlukan penyematan sertifikat, gunakan nama domain kustom dan sertifikat kustom atau Key Vault, bukan sertifikat default atau sertifikat terkelola gratis. Kami tidak menyarankan untuk memiliki ketergantungan kuat pada sertifikat yang tidak Anda kelola sendiri.

Kustom

Jika Anda sudah memiliki sertifikat privat dari penyedia pihak ketiga, Anda dapat mengunggahnya ke instans API Management Anda. Ini harus memenuhi persyaratan berikut. (Jika Anda mengaktifkan sertifikat gratis yang dikelola oleh API Management, sertifikat tersebut sudah memenuhi persyaratan ini.)

• Diekspor sebagai file PFX, dienkripsi menggunakan TIGA DES, dan secara opsional dilindungi kata sandi.
• Berisi kunci privat setidaknya sepanjang 2048 bit
• Berisi semua sertifikat perantara dan sertifikat akar dalam rantai sertifikat.

Key Vault

Sebaiknya gunakan Azure Key Vault untuk mengelola sertifikat Anda dan mengaturnya ke autorenew.

Jika Anda menggunakan Azure Key Vault untuk mengelola sertifikat TLS domain kustom, pastikan sertifikat dimasukkan ke dalam Key Vault sebagai sertifikat, bukan rahasia.

Perhatian

Saat menggunakan sertifikat brankas kunci di API Management, berhati-hatilah untuk tidak menghapus sertifikat, brankas kunci, atau identitas terkelola yang digunakan untuk mengakses brankas kunci.

Untuk mengambil sertifikat TLS/SSL, API Management harus memiliki daftar dan mendapatkan izin rahasia di Azure Key Vault yang berisi sertifikat.

• Saat Anda menggunakan portal Microsoft Azure untuk mengimpor sertifikat, semua langkah konfigurasi yang diperlukan diselesaikan secara otomatis.

• Saat Anda menggunakan alat baris perintah atau API manajemen, izin ini harus diberikan secara manual, dalam dua langkah:

  1. Pada halaman Identitas terkelola instans API Management Anda, aktifkan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna. Perhatikan ID utama di halaman tersebut.
  2. Tetapkan izin ke identitas terkelola untuk mengakses brankas kunci. Gunakan langkah-langkah di bagian berikut.

  Mengonfigurasi akses ke Key Vault

  1. Di portal, buka brankas kunci Anda.
  2. Di menu sebelah kiri, pilih Konfigurasi akses. Perhatikan Model izin yang dikonfigurasi.
  3. Bergantung pada model izin, konfigurasikan kebijakan akses ke brankas kunci atau akses Azure RBAC untuk identitas terkelola API Management.

  Untuk menambahkan kebijakan akses Key Vault:

  1. Di menu sebelah kiri, pilih Kebijakan akses.
  2. Pada halaman Kebijakan akses , pilih + Buat.
  3. Pada tab Izin , di bawah Izin rahasia, pilih Dapatkan dan Daftar, lalu pilih Berikutnya.
  4. Pada tab Utama , pilih Utama, cari nama sumber daya identitas terkelola Anda, lalu pilih Berikutnya. Jika Anda menggunakan identitas yang diberikan oleh sistem, prinsipal adalah nama instans Pengelolaan API Anda.
  5. Pilih Berikutnya lagi. Pada tab Tinjau + buat , pilih Buat.

  Untuk mengonfigurasi akses Azure RBAC:

  1. Di menu sebelah kiri, pilih Kontrol akses (IAM).
  2. Pada halaman Kontrol akses (IAM), pilih Tambahkan penetapan peran.
  3. Pada tab Peran , pilih Pengguna Sertifikat Key Vault.
  4. Pada tab Anggota, pilih Identitas> terkelola+ Pilih anggota.
  5. Di jendela Pilih identitas terkelola , pilih identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang terkait dengan instans API Management Anda, lalu klik Pilih.
  6. Pilih Tinjau + tetapkan.

Jika sertifikat diatur ke autorenew dan tingkat API Management Anda memiliki SLA (yaitu, di semua tingkatan kecuali tingkat Pengembang), API Management akan mengambil versi terbaru secara otomatis, tanpa gangguan pada layanan.

Untuk informasi selengkapnya, lihat Menggunakan identitas terkelola di Azure API Management.

Dikelola

API Management menawarkan sertifikat TLS terkelola gratis untuk domain Anda, jika Anda tidak ingin membeli dan mengelola sertifikat Anda sendiri. Sertifikat diperbarui otomatis.

Nota

Sertifikat TLS gratis yang dikelola saat ini dalam tahap pratinjau. Saat ini, tidak tersedia di tingkat layanan v2.

Keterbatasan

• Saat ini hanya dapat digunakan dengan endpoint Gateway dari layanan API Management Anda
• Tidak didukung oleh gateway yang dihost secara mandiri
• Tidak didukung di wilayah Azure berikut: Prancis Selatan dan Afrika Selatan Barat
• Saat ini hanya tersedia di cloud Azure
• Tidak mendukung nama domain akar (misalnya, contoso.com). Memerlukan nama yang sepenuhnya memenuhi syarat seperti api.contoso.com.
• Hanya mendukung nama domain publik
• Hanya dapat dikonfigurasi saat memperbarui instans API Management yang ada, bukan saat membuat instans

Mengatur nama domain kustom - portal

Pilih langkah-langkah sesuai dengan sertifikat domain yang ingin Anda gunakan.

Kustom

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang sudah ada yang ingin Anda perbarui.
4. Di jendela di sebelah kanan, pilih Jenis titik akhir untuk domain kustom.
5. Di bidang Nama host , tentukan nama yang ingin Anda gunakan. Contohnya, api.contoso.com.
6. Di bawah Sertifikat, pilih Kustom
7. Pilih File sertifikat untuk memilih dan mengunggah sertifikat.
8. Unggah file .PFX yang valid dan berikan Kata Sandinya, jika sertifikat dilindungi dengan kata sandi.
9. Saat mengonfigurasi titik akhir Gateway, pilih atau batal pilih opsi lain seperlunya, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL Default.
10. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang sudah ada.
11. Pilih Simpan.

Key Vault

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang sudah ada yang ingin Anda perbarui.
4. Di jendela di sebelah kanan, pilih Jenis titik akhir untuk domain kustom.
5. Di bidang Nama host , tentukan nama yang ingin Anda gunakan. Contohnya, api.contoso.com.
6. Di bawah Sertifikat, pilih Key Vault lalu Pilih.
   1. Pilih Langganan dari daftar dropdown.
   2. Pilih Brankas kunci dari menu tarik-turun.
   3. Setelah sertifikat dimuat, pilih Sertifikat dari daftar dropdown. Klik Pilih.
   4. Di Identitas klien, pilih identitas yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang diaktifkan dalam instans untuk mengakses brankas kunci.
7. Saat mengonfigurasi titik akhir Gateway, pilih atau batal pilih opsi lain seperlunya, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL Default.
8. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang sudah ada.
9. Pilih Simpan.

Dikelola

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang sudah ada yang ingin Anda perbarui.
4. Di jendela di sebelah kanan, pilih Jenis titik akhir untuk domain kustom.
5. Di bidang Nama host , tentukan nama yang ingin Anda gunakan. Contohnya, api.contoso.com.
6. Di bawah Sertifikat, pilih Dikelola untuk mengaktifkan sertifikat gratis yang dikelola oleh API Management. Sertifikat terkelola hanya tersedia dalam pratinjau untuk titik akhir Gateway.
7. Salin nilai berikut dan gunakan untuk mengonfigurasi DNS:
   • Catatan TXT
   • Rekor CNAME
8. Saat mengonfigurasi titik akhir Gateway, pilih atau batal pilih opsi lain seperlunya, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL Default.
9. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang sudah ada.
10. Pilih Simpan.

Konfigurasi DNS

• Mengonfigurasi data CNAME untuk domain kustom Anda.
• Saat menggunakan sertifikat terkelola GRATIS API Management, konfigurasikan juga catatan TXT untuk membuat kepemilikan domain Anda.

Nota

Sertifikat gratis dikeluarkan oleh DigiCert. Untuk beberapa domain, Anda harus secara eksplisit mengizinkan DigiCert sebagai penerbit sertifikat dengan membuat catatan domain CAA dengan nilai : 0 issue digicert.com.

Catatan CNAME

Konfigurasikan data CNAME yang menunjuk dari nama domain kustom Anda (misalnya, api.contoso.com) ke nama host layanan API Management Anda (misalnya, <apim-service-name>.azure-api.net). Catatan CNAME lebih stabil daripada catatan A jika alamat IP berubah. Untuk informasi selengkapnya, lihat Alamat IP Azure API Management dan FAQ API Management.

Nota

Beberapa pencatat domain hanya memungkinkan Anda memetakan subdomain saat menggunakan data CNAME, seperti www.contoso.com, dan bukan nama akar, seperti contoso.com. Untuk informasi selengkapnya tentang catatan CNAME, lihat dokumentasi yang disediakan oleh pencatat atau Nama Domain IETF Anda - Implementasi dan Spesifikasi.

Perhatian

Saat Anda menggunakan sertifikat terkelola gratis dan mengonfigurasi catatan CNAME dengan penyedia DNS Anda, pastikan alamat tersebut mengarah ke nama host layanan API Management default (<apim-service-name>.azure-api.net). Saat ini, API Management tidak secara otomatis memperbarui sertifikat jika data CNAME tidak mengarah ke nama host default API Management. Misalnya, jika Anda menggunakan sertifikat terkelola gratis dan Anda menggunakan Cloudflare sebagai penyedia DNS Anda, pastikan bahwa proksi DNS tidak diaktifkan pada data CNAME.

Catatan TXT

Saat mengaktifkan sertifikat terkelola gratis untuk API Management, konfigurasikan juga catatan TXT di zona DNS Anda untuk menetapkan kepemilikan nama domain Anda.

• Nama catatan adalah nama domain kustom Anda yang diawali oleh apimuid. Contoh: apimuid.api.contoso.com.
• Nilainya adalah pengidentifikasi kepemilikan domain yang disediakan oleh instans API Management Anda.

Saat Anda menggunakan portal untuk mengonfigurasi sertifikat terkelola gratis untuk domain kustom Anda, nama dan nilai catatan TXT yang diperlukan akan ditampilkan secara otomatis.

Anda juga bisa mendapatkan pengidentifikasi kepemilikan domain dengan memanggil REST API Dapatkan Pengidentifikasi Kepemilikan Domain .

Bagaimana server proksi API Management merespons dengan sertifikat SSL dalam jabat tangan TLS

Saat mengonfigurasi domain kustom untuk titik akhir Gateway, Anda dapat mengatur properti tambahan yang menentukan bagaimana API Management merespons dengan sertifikat server, tergantung pada permintaan klien.

Klien-klien yang menelepon dengan header Indikasi Nama Server (SNI)

Jika Anda memiliki satu atau beberapa domain kustom yang dikonfigurasi untuk titik akhir Gateway, API Management dapat menanggapi permintaan HTTPS dari:

• Domain kustom (misalnya, contoso.com)
• Domain default (misalnya, apim-service-name.azure-api.net).

Berdasarkan informasi di header SNI, API Management merespons dengan sertifikat server yang sesuai.

Klien memanggil tanpa header SNI

Jika Anda menggunakan klien yang tidak mengirim header SNI , API Management membuat respons berdasarkan logika berikut:

• Jika layanan hanya memiliki satu domain kustom yang dikonfigurasi untuk Gateway, sertifikat default adalah sertifikat yang dikeluarkan untuk domain kustom Gateway.

• Jika layanan telah mengonfigurasi beberapa domain kustom untuk Gateway (didukung di tingkat Pengembang dan Premium ), Anda dapat menunjuk sertifikat default dengan mengatur properti defaultSslBinding ke true ("defaultSslBinding":"true"). Di portal, pilih kotak centang Pengikatan SSL Default .

  Jika Anda tidak mengatur properti, sertifikat default adalah sertifikat yang dikeluarkan ke domain Gateway default yang dihosting di *.azure-api.net.

Dukungan untuk permintaan PUT/POST dengan payload besar

Server proksi API Management mendukung permintaan dengan payload besar (>40 KB) saat menggunakan sertifikat sisi klien di HTTPS. Untuk mencegah permintaan server membeku, Anda dapat mengatur properti negotiateClientCertificate ke true ("negotiateClientCertificate": "true") pada nama host Gateway. Di portal, pilih kotak centang Negosiasikan sertifikat klien .

Jika properti diatur ke benar, sertifikat klien diminta saat koneksi SSL/TLS berlangsung, sebelum pertukaran permintaan HTTP apa pun. Karena pengaturan berlaku di tingkat Nama host Gateway , semua permintaan koneksi meminta sertifikat klien. Anda dapat mengatasi batasan ini dan mengonfigurasi hingga 20 domain kustom untuk Gateway (hanya didukung di tingkat Premium ).

Batasan untuk nama domain kustom di tingkat Standar v2

Saat ini, di tingkat Standar v2, API Management memerlukan nama DNS yang dapat diselesaikan secara publik untuk memungkinkan lalu lintas ke titik akhir Gateway. Jika Anda mengonfigurasi nama domain kustom untuk titik akhir Gateway, nama tersebut harus dapat diselesaikan secara publik, tidak dibatasi untuk zona DNS privat.

Sebagai solusi dalam skenario di mana Anda membatasi akses publik ke gateway dan mengonfigurasi nama domain privat, Anda dapat menyiapkan Application Gateway untuk menerima lalu lintas di nama domain privat dan merutekannya ke titik akhir Gateway instans API Management. Untuk contoh arsitektur, lihat repositori GitHub ini.

Pemecahan masalah: Rotasi sertifikat nama host dari Azure Key Vault gagal

Karena perubahan konfigurasi atau masalah konektivitas, instans API Management Anda mungkin tidak dapat mengambil sertifikat nama host dari Azure Key Vault setelah sertifikat diperbarui atau diputar di sana. Ketika ini terjadi, instans API Management Anda terus menggunakan sertifikat yang di-cache hingga menerima sertifikat yang diperbarui. Jika sertifikat yang di-cache kedaluwarsa, lalu lintas runtime ke gateway akan diblokir. Setiap layanan upstream seperti Application Gateway yang menggunakan konfigurasi sertifikat nama host juga dapat memblokir lalu lintas runtime ke gateway saat sertifikat cache yang kedaluwarsa digunakan.

Untuk mengurangi masalah ini, konfirmasikan bahwa brankas kunci ada, dan sertifikat disimpan di brankas kunci. Jika instans API Management Anda disebarkan di jaringan virtual, konfirmasikan konektivitas eksternal ke tag layanan Azure Key Vault. Periksa apakah identitas terkelola yang digunakan untuk mengakses brankas kunci ada. Konfirmasikan izin identitas terkelola untuk mengakses brankas kunci. Tinjau Menyiapkan nama domain kustom - Key Vault, sebelumnya dalam artikel ini, untuk langkah-langkah konfigurasi terperinci. Setelah konfigurasi dipulihkan, sertifikat nama host akan di-refresh di API Management dalam waktu 4 jam.

Konten terkait

Meningkatkan dan menskalakan layanan Anda