Bagikan melalui

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

  • Artikel

BERLAKU UNTUK: Semua tingkatAN 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 halus, praotorisasi permintaan yang meneruskan token OAuth 2.0 yang dihasilkan oleh idP seperti ID Microsoft Entra.

Untuk latar belakang, lihat:

Prasyarat

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

  • Sebuah instans API Management. Misalnya 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 bernama kemudian dapat dirujuk dalam kebijakan API untuk mengatur api-key header dalam permintaan ke Azure OpenAI API. Kami memberikan dua contoh cara melakukan ini: satu menggunakan set-backend-service kebijakan, 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 di halaman Kunci dan Titik Akhir 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 lainnya, gunakan referensi brankas kunci.

Meneruskan kunci API dalam permintaan API - kebijakan set-backend-service

  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 Header, dan masukkan api-key sebagai nama header dan nilai bernama sebagai nilai .
    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" />

Meneruskan kunci API dalam permintaan API - kebijakan 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 untuk mengautentikasi ke Azure OpenAI API 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, yang terlingkup ke sumber daya yang sesuai. Misalnya, tetapkan identitas terkelola yang ditetapkan sistem peran Pengguna OpenAI Cognitive Services 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>

Otorisasi OAuth 2.0 menggunakan IdP

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 idP Anda untuk mewakili Api OpenAI di Azure API Management. Jika Anda menggunakan ID Microsoft Entra, daftarkan aplikasi di penyewa ID Microsoft Entra Anda. Catat detail seperti ID aplikasi dan URI audiens.

    Sesuai kebutuhan, konfigurasikan aplikasi untuk memiliki peran atau cakupan yang mewakili izin menenangkan 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 Azure OpenAI API.

    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 referensi 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 IdP lain, konfigurasikan validate-jwt kebijakan untuk memvalidasi audiens dan klaim di JWT. Untuk detailnya, lihat referensi 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