Bagikan melalui

Mengautentikasi dan mengotorisasi akses ke API Azure OpenAI menggunakan Azure API Management

BERLAKU UNTUK: Semua tingkat API Management

Dalam artikel ini, Anda mempelajari cara mengautentikasi dan mengotorisasi ke titik akhir Azure OpenAI API yang dikelola menggunakan Azure API Management. Artikel ini memperlihatkan metode umum berikut:

  • Autentikasi - Autentikasi ke AZURE OpenAI API menggunakan kebijakan yang mengautentikasi menggunakan kunci API atau identitas terkelola ID Microsoft Entra.

  • Otorisasi - Untuk kontrol akses yang lebih rinci, praotorisasi permintaan yang meneruskan token OAuth 2.0 yang dihasilkan oleh penyedia identitas seperti Microsoft Entra ID.

Untuk latar belakang, lihat:

Prasyarat

Sebelum mengikuti langkah-langkah dalam artikel ini, Anda harus memiliki:

  • Sebuah instance Manajemen API. Misalnya, untuk langkah-langkah, lihat Membuat instans Azure API Management.
  • Sumber daya dan model Azure OpenAI ditambahkan ke instans API Management Anda. Misalnya langkah-langkah, lihat Mengimpor Api Azure OpenAI sebagai REST API.
  • Izin untuk membuat pendaftaran aplikasi di penyedia identitas seperti penyewa Microsoft Entra yang terkait dengan langganan Azure Anda (untuk otorisasi OAuth 2.0).

Mengautentikasi dengan kunci API

Cara default untuk mengautentikasi ke Azure OpenAI API adalah dengan menggunakan kunci API. Untuk jenis autentikasi ini, semua permintaan API harus menyertakan kunci API yang valid di api-key header HTTP.

  • API Management dapat mengelola kunci API dengan cara yang aman, dengan menggunakan nilai bernama.
  • Nilai yang telah diberi nama dapat digunakan dalam kebijakan API untuk mengatur header api-key dalam permintaan ke Azure OpenAI API. Kami memberikan dua contoh cara melakukan ini: satu menggunakan kebijakan set-backend-service, dan yang lain menggunakan kebijakan set-header.

Menyimpan kunci API dalam nilai bernama

  1. Dapatkan kunci API dari sumber daya Azure OpenAI. Di portal Azure, temukan kunci pada halaman Keys dan Endpoint dari sumber daya Azure OpenAI.
  2. Buka instans API Management Anda, dan pilih Nilai bernama di menu sebelah kiri.
  3. Pilih + Tambahkan, dan tambahkan nilai sebagai rahasia, atau secara opsional untuk keamanan tambahan, gunakan referensi lemari besi kunci.

Teruskan kunci API dalam permintaan API - kebijakan pengaturan layanan backend

  1. Buat backend yang menunjuk ke Azure OpenAI API.

    1. Di menu sebelah kiri instans API Management Anda, pilih Backend.
    2. Pilih + Tambahkan, dan masukkan nama deskriptif untuk backend. Contoh: openai-backend.
    3. Di bawah Jenis, pilih Kustom, dan masukkan URL titik akhir Azure OpenAI. Contoh: https://contoso.openai.azure.com/openai.
    4. Di bawah Kredensial Otorisasi, pilih Headers, dan masukkan api-key sebagai nama header dan nilai yang ditetapkan sebagai nilainya.
    5. Pilih Buat.

  2. Tambahkan cuplikan kebijakan berikut set-backend-service di bagian inbound kebijakan untuk meneruskan kunci API dalam permintaan ke Azure OpenAI API.

    Dalam contoh ini, sumber daya backend adalah openai-backend.

    <set-backend-service backend-id="openai-backend" />

Sertakan kunci API dalam permintaan API - aturan set-header

Atau, tambahkan cuplikan kebijakan berikut set-header di bagian inbound kebijakan untuk meneruskan kunci API dalam permintaan ke Azure OpenAI API. Cuplikan kebijakan ini mengatur api-key header dengan nilai bernama yang Anda siapkan.

Dalam contoh ini, nilai bernama dalam API Management adalah openai-api-key.

<set-header name="api-key" exists-action="override">
    <value>{{openai-api-key}}</value>
</set-header>

Mengautentikasi dengan identitas terkelola

Cara alternatif dan direkomendasikan untuk mengautentikasi ke Azure OpenAI API adalah dengan menggunakan identitas terkelola di ID Microsoft Entra. Untuk latar belakang, lihat Cara mengonfigurasi Azure OpenAI Service dengan identitas terkelola.

Berikut ini adalah langkah-langkah untuk mengonfigurasi instans API Management Anda untuk menggunakan identitas terkelola untuk mengautentikasi permintaan ke Azure OpenAI API.

  1. Aktifkan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna untuk instans API Management Anda. Contoh berikut mengasumsikan bahwa Anda telah mengaktifkan identitas terkelola yang ditetapkan sistem instans.

  2. Tetapkan identitas terkelola peran Pengguna OpenAI Cognitive Services, dengan cakupan ke sumber daya yang sesuai. Misalnya, tetapkan identitas terkelola yang ditetapkan sistem sebagai peran Cognitive Services OpenAI User pada sumber daya Azure OpenAI. Untuk langkah-langkah terperinci, lihat Kontrol akses berbasis peran untuk layanan Azure OpenAI.

  3. Tambahkan cuplikan kebijakan berikut di bagian inbound kebijakan untuk mengautentikasi permintaan ke Azure OpenAI API menggunakan identitas terkelola.

    Dalam contoh ini:

    <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
<set-header name="Authorization" exists-action="override"> 
    <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
</set-header>

Petunjuk / Saran

Alternatif untuk menggunakan kebijakan dan authentication-managed-identity yang set-header ditampilkan dalam contoh ini adalah mengonfigurasi sumber daya backend yang mengarahkan permintaan API ke titik akhir Azure OpenAI Service. Dalam konfigurasi backend, aktifkan autentikasi identitas terkelola ke Layanan Azure OpenAI. Azure API Management mengotomatiskan langkah-langkah ini saat mengimpor API langsung dari Azure OpenAI Service. Untuk informasi selengkapnya, lihat Mengimpor API dari Azure OpenAI Service.

Otorisasi OAuth 2.0 menggunakan penyedia identitas

Untuk mengaktifkan akses yang lebih terperinci ke API OpenAPI oleh pengguna atau klien tertentu, Anda dapat melakukan praotorisasi akses ke Azure OpenAI API menggunakan otorisasi OAuth 2.0 dengan ID Microsoft Entra atau penyedia identitas lain. Untuk latar belakang, lihat Melindungi API di Azure API Management menggunakan otorisasi OAuth 2.0 dengan ID Microsoft Entra.

Catatan

Gunakan otorisasi OAuth 2.0 sebagai bagian dari strategi pertahanan mendalam. Ini bukan pengganti untuk autentikasi kunci API atau autentikasi identitas terkelola ke Azure OpenAI API.

Berikut ini adalah langkah-langkah tingkat tinggi untuk membatasi akses API ke pengguna atau aplikasi yang diotorisasi menggunakan penyedia identitas.

  1. Buat aplikasi di penyedia identitas Anda untuk mewakili API OpenAI di Azure API Management. Jika Anda menggunakan Microsoft Entra ID, daftarkan aplikasi dalam tenant Microsoft Entra ID Anda. Catat detail seperti ID aplikasi dan URI audiens.

    Sesuai kebutuhan, konfigurasikan aplikasi untuk memiliki peran atau lingkup yang mewakili izin detil yang diperlukan untuk mengakses Azure OpenAI API.

  2. Tambahkan cuplikan inbound kebijakan di instans API Management Anda untuk memvalidasi permintaan yang menyajikan token web JSON (JWT) di Authorization header. Tempatkan cuplikan ini sebelum kebijakan lain inbound yang Anda tetapkan untuk mengautentikasi ke API Azure OpenAI.

    Catatan

    Contoh berikut menunjukkan struktur umum kebijakan untuk memvalidasi JWT. Sesuaikan dengan penyedia identitas Anda dan persyaratan aplikasi dan API Anda.

    • validate-azure-ad-token - Jika Anda menggunakan ID Microsoft Entra, konfigurasikan validate-azure-ad-token kebijakan untuk memvalidasi audiens dan klaim di JWT. Untuk detailnya, lihat acuan kebijakan.

      <validate-azure-ad-token tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <client-application-ids>
            <application-id>{{CLIENT_APP_ID}}</application-id>
    </client-application-ids>
   <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

    • validate-jwt - Jika Anda menggunakan penyedia identitas lain, konfigurasikan kebijakan validate-jwt untuk memvalidasi audiens dan klaim dalam JWT. Untuk detailnya, lihat acuan kebijakan.

      <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url={{OPENID_CONFIGURATION_URL}} />
    <issuers>
        <issuer>{{ISSUER_URL}}</issuer>
    </issuers>
    <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-jwt>

Konten terkait