Sdílet prostřednictvím

Ověřování a autorizace přístupu k rozhraním API Azure OpenAI pomocí služby Azure API Management

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

V tomto článku se dozvíte o způsobech ověřování a autorizace koncových bodů rozhraní API Azure OpenAI spravovaných pomocí služby Azure API Management. Tento článek ukazuje následující běžné metody:

  • Ověřování – Ověřování v rozhraní Azure OpenAI API pomocí zásad, které se ověřují pomocí klíče rozhraní API nebo spravované identity Microsoft Entra ID.

  • Autorizace – U jemněji odstupňovaného řízení přístupu předvytváření požadavků, které předávají tokeny OAuth 2.0 vygenerované zprostředkovatelem identity, jako je ID Microsoft Entra.

Pozadí najdete tady:

Požadavky

Než budete postupovat podle kroků v tomto článku, musíte mít:

  • Instance služby API Management. Příklad kroků najdete v tématu Vytvoření instance služby Azure API Management.
  • Prostředek a model Azure OpenAI přidaný do vaší instance služby API Management. Příklad kroků najdete v tématu Import rozhraní API Azure OpenAI jako rozhraní REST API.
  • Oprávnění k vytvoření registrace aplikace v zprostředkovateli identity, jako je tenant Microsoft Entra přidružený k vašemu předplatnému Azure (pro autorizaci OAuth 2.0).

Ověření pomocí klíče rozhraní API

Výchozí způsob ověřování v rozhraní API Azure OpenAI je použití klíče rozhraní API. Pro tento typ ověřování musí všechny požadavky rozhraní API obsahovat platný klíč rozhraní API v api-key hlavičce HTTP.

  • Služba API Management může klíč rozhraní API bezpečně spravovat pomocí pojmenované hodnoty.
  • Na pojmenovanou hodnotu pak můžete odkazovat v zásadách rozhraní API, aby se hlavička api-key v požadavcích na rozhraní API Azure OpenAI nastavila. Nabízíme dva příklady, jak to udělat: jeden používá zásadu set-backend-service a druhá používá zásadu set-header .

Uložení klíče rozhraní API do pojmenované hodnoty

  1. Získejte klíč rozhraní API z prostředku Azure OpenAI. Na webu Azure Portal vyhledejte klíč na stránce Klíče a koncový bod prostředku Azure OpenAI.
  2. Přejděte do instance služby API Management a v nabídce vlevo vyberte Pojmenované hodnoty .
  3. Vyberte + Přidat a přidejte hodnotu jako tajný klíč nebo volitelně pro větší zabezpečení použijte odkaz na trezor klíčů.

Předání klíče rozhraní API v požadavcích rozhraní API – zásady set-back-endové služby

  1. Vytvořte back-end , který odkazuje na rozhraní API Azure OpenAI.

    1. V levé nabídce instance služby API Management vyberte back-endy.
    2. Vyberte + Přidat a zadejte popisný název back-endu. Příklad: openai-back-end.
    3. V části Typ vyberte Vlastní a zadejte adresu URL koncového bodu Azure OpenAI. Příklad: https://contoso.openai.azure.com/openai.
    4. V části Autorizační přihlašovací údaje vyberte Hlavičky a jako název hlavičky zadejte klíč api-key a pojmenovanou hodnotu jako hodnotu.
    5. Vyberte Vytvořit.

  2. Do části zásady přidejte následující set-backend-service fragment kódu inbound zásad, který předá klíč rozhraní API v požadavcích do rozhraní API Azure OpenAI.

    V tomto příkladu je back-endový prostředek openai-back-end.

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

Předání klíče rozhraní API v požadavcích rozhraní API – zásady set-header

Případně přidejte do části zásady následující set-header fragment kódu inbound zásad, který předá klíč rozhraní API v požadavcích do rozhraní API Azure OpenAI. Tento fragment kódu zásady nastaví hlavičku api-key s pojmenovanou hodnotou, kterou jste nastavili.

V tomto příkladu je pojmenovaná hodnota ve službě API Management openai-api-key.

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

Ověřování pomocí spravované identity

Alternativní způsob ověřování v rozhraní API Azure OpenAI pomocí spravované identity v Microsoft Entra ID. Pozadí najdete v tématu Konfigurace služby Azure OpenAI s využitím spravované identity.

V následujících krocích nakonfigurujete instanci služby API Management tak, aby používala spravovanou identitu k ověřování požadavků na rozhraní API Azure OpenAI.

  1. Povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem pro vaši instanci služby API Management. Následující příklad předpokládá, že jste povolili spravovanou identitu přiřazenou systémem instance.

  2. Přiřaďte spravovanou identitu roli uživatele OpenAI služeb Cognitive Services s oborem odpovídajícího prostředku. Například přiřaďte spravovanou identitu přiřazenou systémem roli uživatele OpenAI služeb Cognitive Services v prostředku Azure OpenAI. Podrobné kroky najdete v tématu Řízení přístupu na základě role pro službu Azure OpenAI.

  3. Do části zásady přidejte následující fragment kódu inbound zásad pro ověřování požadavků na rozhraní AZURE OpenAI API pomocí spravované identity.

    V tomto příkladu:

    <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>

Autorizace OAuth 2.0 pomocí zprostředkovatele identity

Pokud chcete konkrétním uživatelům nebo klientům povolit jemněji odstupňovaný přístup k rozhraním OpenAPI API, můžete předem autorizovat přístup k rozhraní API Azure OpenAI pomocí autorizace OAuth 2.0 pomocí Microsoft Entra ID nebo jiného zprostředkovatele identity. Základní informace najdete v tématu Ochrana rozhraní API ve službě Azure API Management pomocí autorizace OAuth 2.0 s ID Microsoft Entra.

Poznámka:

Autorizace OAuth 2.0 se používá jako součást hloubkové strategie ochrany. Nejedná se o náhradu za ověřování klíče rozhraní API ani ověřování spravované identity v rozhraní API Azure OpenAI.

Následuje obecný postup omezení přístupu rozhraní API k uživatelům nebo aplikacím, které jsou autorizované pomocí zprostředkovatele identity.

  1. Ve zprostředkovateli identity vytvořte aplikaci, která bude reprezentovat rozhraní API OpenAI ve službě Azure API Management. Pokud používáte ID Microsoft Entra, zaregistrujte aplikaci v tenantovi Microsoft Entra ID. Záznam podrobností, jako je ID aplikace a identifikátor URI cílové skupiny.

    Podle potřeby nakonfigurujte aplikaci tak, aby měla role nebo obory, které představují jemně odstupňovaná oprávnění potřebná pro přístup k rozhraní Azure OpenAI API.

  2. inbound Přidejte do instance služby API Management fragment zásad a ověřte požadavky, které v hlavičce obsahují webový token JSON (JWTAuthorization). Umístěte tento fragment kódu před další inbound zásady, které jste nastavili pro ověření v rozhraní AZURE OpenAI API.

    Poznámka:

    Následující příklady ukazují obecnou strukturu zásad pro ověření JWT. Přizpůsobte je poskytovateli identity a požadavkům vaší aplikace a rozhraní API.

    • validate-azure-ad-token – Pokud používáte ID Microsoft Entra, nakonfigurujte zásadu validate-azure-ad-token pro ověření cílové skupiny a deklarací identity v JWT. Podrobnosti najdete v referenčních informacích k zásadám.

      <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 – Pokud používáte jiného zprostředkovatele identity, nakonfigurujte validate-jwt zásadu pro ověření cílové skupiny a deklarací identity v JWT. Podrobnosti najdete v referenčních informacích k zásadám.

      <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>

Související obsah