Mengonfigurasi nama domain kustom untuk instans Azure API Management Anda

BERLAKU UNTUK: Semua tingkatAN API Management

Saat Anda membuat instans layanan Azure API Management di Azure cloud, Azure menetapkannya sebagai azure-api.net subdomain (misalnya, apim-service-name.azure-api.net). Anda dapat mengekspos titik akhir API Management Anda menggunakan nama domain kustom Anda sendiri, seperti contoso.com. Artikel ini menunjukkan 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 default Gateway
• Salah satu nama domain kustom yang dikonfigurasi Gateway

Prasyarat

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

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

• 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 untuk mengekspos URL melalui TLS dengan aman).

  Lihat Opsi sertifikat domain.

• Rekaman DNS yang dihosting di server DNS untuk memetakan nama domain kustom ke nama domain default dari instans API Management Anda. Topik ini tidak memberikan petunjuk tentang cara menghosting data DNS.

  Untuk informasi selengkapnya tentang data yang diperlukan, lihat konfigurasi DNS, nanti di artikel ini.

Titik akhir untuk domain kustom

Ada beberapa titik akhir API Management tempat Anda dapat menetapkan nama domain kustom. Saat ini, titik akhir berikut tersedia:

Titik akhir	Default
Gateway	Defaultnya adalah: <apim-service-name>.azure-api.net. Hanya titik akhir Gateway yang tersedia untuk konfigurasi di tingkat Konsumsi. Konfigurasi titik akhir Gateway default tetap tersedia setelah domain Gateway kustom ditambahkan.
Portal pengembang	Defaultnya adalah: <apim-service-name>.developer.azure-api.net
Manajemen	Defaultnya adalah: <apim-service-name>.management.azure-api.net
API Konfigurasi (v2)	Defaultnya adalah: <apim-service-name>.configuration.azure-api.net
SCM	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 Manajemen dan SCM secara internal. Titik akhir ini lebih jarang mendapatkan nama domain kustom.
• Tingkat Premium dan Pengembang mendukung pengaturan beberapa nama host untuk titik akhir Gateway.
• Nama domain kartubebas, seperti *.contoso.com, didukung di semua tingkatan kecuali tingkat Konsumsi. Sertifikat subdomain tertentu (misalnya, api.contoso.com) akan lebih diutamakan daripada sertifikat kartubebas (*.contoso.com) agar permintaan api.contoso.com.

Opsi sertifikat domain

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

Peringatan

Jika Anda memerlukan penyematan sertifikat, disarankan menggunakan nama domain kustom dan sertifikat Key Vault atau kustom, bukan sertifikat default atau sertifikat terkelola gratis. Kami tidak menyarankan untuk mengambil dependensi keras pada sertifikat yang tidak Anda kelola.

Adat

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

• Diekspor sebagai file PFX, dienkripsi menggunakan triple 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 tersebut 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 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 dari instans API Management Anda, aktifkan identitas terkelola yang ditetapkan sistem atau 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 brankas kunci

  1. Di portal, arahkan ke brankas kunci Anda.

  2. Di menu sebelah kiri, pilih Konfigurasi akses, dan perhatikan Model izin yang dikonfigurasi.

  3. Bergantung pada model izin, konfigurasikan kebijakan akses brankas kunci atau akses Azure RBAC untuk identitas terkelola API Management.

     Untuk menambahkan kebijakan akses brankas kunci:
     

     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 prinsipal, cari nama sumber daya identitas terkelola Anda, lalu pilih Berikutnya. Jika Anda menggunakan identitas yang ditetapkan sistem, prinsipal adalah nama instans API Management Anda.
     5. Pilih Berikutnya lagi. Di 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 Rahasia Key Vault.
     4. Pada tab Anggota, pilih Identitas> terkelola+ Pilih anggota.
     5. Pada halaman Pilih identitas terkelola, pilih identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna yang terkait dengan instans API Management Anda, lalu pilih Pilih.
     6. Pilih Tinjau + tetapkan.

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

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

Terkelola

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

Catatan

Sertifikat TLS terkelola gratis sedang dalam pratinjau. Saat ini, tidak tersedia di tingkat layanan v2.

Batasan

• Saat ini hanya dapat digunakan dengan titik akhir Gateway layanan API Management Anda
• Tidak didukung dengan gateway yang dihost sendiri
• Tidak didukung di wilayah Azure berikut: Prancis Selatan dan Afrika Selatan Barat
• Saat ini hanya tersedia di cloud Azure
• Tidak mendukung nama domain root (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-langkahnya sesuai dengan sertifikat domain yang ingin Anda gunakan.

Adat

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi sebelah kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang 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 sediakan Kata Sandinya, jika sertifikat dilindungi dengan kata sandi.
9. Saat mengonfigurasi titik akhir Gateway, pilih atau batalkan pilihan opsi lain yang diperlukan, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL default.
10. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang ada.
11. Pilih Simpan.

Key Vault

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi sebelah kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang 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 pilihan menurun.
   2. Pilih Key Vault dari daftar pilihan menurun.
   3. Setelah sertifikat dimuat, pilih Sertifikat dari daftar pilihan menurun. 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 batalkan pilihan opsi lain yang diperlukan, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL default.
8. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang ada.
9. Pilih Simpan.

Terkelola

1. Navigasikan ke instans API Management Anda di portal Microsoft Azure.
2. Di navigasi sebelah kiri, pilih Domain kustom.
3. Pilih +Tambahkan, atau pilih titik akhir yang 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 Terkelola 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
   • Cname
8. Saat mengonfigurasi titik akhir Gateway, pilih atau batalkan pilihan opsi lain yang diperlukan, termasuk Negosiasikan sertifikat klien atau Pengikatan SSL default.
9. Pilih Tambahkan, atau pilih Perbarui untuk titik akhir yang ada.
10. Pilih Simpan.

Catatan

Proses penetapan sertifikat mungkin memakan waktu 15 menit atau lebih tergantung pada ukuran penyebaran. Tingkat pengembang memiliki waktu henti, sementara SKU Dasar dan yang lebih tinggi tidak memiliki waktu henti.

Konfigurasi DNS

• Mengonfigurasi data CNAME untuk domain kustom Anda.
• Saat menggunakan sertifikat terkelola gratis dari API Management, konfigurasikan juga rekaman TXT untuk menetapkan kepemilikan domain Anda.

Catatan

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

Catatan CN

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

Catatan

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

Perhatian

Saat Anda menggunakan sertifikat terkelola gratis dan mengonfigurasi data CNAME dengan penyedia DNS Anda, pastikan sertifikat tersebut diselesaikan ke nama host layanan API Management default (<apim-service-name>.azure-api.net). Saat ini, API Management tidak memperbarui sertifikat secara otomatis jika data CNAME tidak diselesaikan ke nama host API Management default. 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 rekaman TXT di zona DNS Anda untuk menetapkan kepemilikan nama domain Anda.

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

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

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

Bagaimana server proksi API Management merespons dengan sertifikat SSL di handshake TLS

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

Klien menelepon dengan header Indikasi Nama Server (SNI)

Jika Anda memiliki satu atau beberapa domain kustom yang dikonfigurasi untuk titik akhir Gateway, API Management dapat merespons 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 tajuk 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 menetapkan sertifikat default dengan mengatur defaultSslBinding menjadi benar ("defaultSslBinding":"true"). Di portal, pilih kotak centang Pengikatan SSL default.

  Jika Anda tidak mengatur properti, sertifikat default adalah sertifikat yang diterbitkan untuk 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 (>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 true, sertifikat klien diminta pada waktu sambungan SSL/TLS, sebelum pertukaran permintaan HTTP apa pun. Karena pengaturan berlaku di tingkat Gateway hostname, semua permintaan sambungan meminta sertifikat klien. Anda dapat mengatasi batasan ini dan mengonfigurasi hingga 20 domain kustom untuk Gateway (hanya didukung di tingkat Premium).

Langkah berikutnya

Tingkatkan dan skalakan layanan Anda