Udostępnij za pośrednictwem

Uwierzytelnianie i autoryzacja dostępu do interfejsów API usługi Azure OpenAI przy użyciu usługi Azure API Management

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

W tym artykule przedstawiono sposoby uwierzytelniania i autoryzacji punktów końcowych interfejsu API openAI platformy Azure zarządzanych przy użyciu usługi Azure API Management. W tym artykule przedstawiono następujące typowe metody:

  • Uwierzytelnianie — uwierzytelnianie w interfejsie API usługi Azure OpenAI przy użyciu zasad, które uwierzytelniają się przy użyciu klucza interfejsu API lub tożsamości zarządzanej identyfikatora entra firmy Microsoft.

  • Autoryzacja — aby uzyskać bardziej szczegółową kontrolę dostępu, wstępnie uwierzytelniaj żądania, które przekazują tokeny OAuth 2.0 generowane przez dostawcę tożsamości, takiego jak Microsoft Entra ID.

Aby zapoznać się z tłem, zobacz:

Wymagania wstępne

Przed wykonaniem kroków opisanych w tym artykule musisz mieć następujące elementy:

  • Wystąpienie usługi API Management. Aby uzyskać przykładowe kroki, zobacz Tworzenie wystąpienia usługi Azure API Management.
  • Zasób i model usługi Azure OpenAI dodany do wystąpienia usługi API Management. Aby uzyskać przykładowe kroki, zobacz Importowanie interfejsu API usługi Azure OpenAI jako interfejsu API REST.
  • Uprawnienia do tworzenia rejestracji aplikacji u dostawcy tożsamości, takiego jak dzierżawa firmy Microsoft Entra skojarzona z subskrypcją platformy Azure (na potrzeby autoryzacji OAuth 2.0).

Uwierzytelnianie przy użyciu klucza interfejsu API

Domyślnym sposobem uwierzytelniania w interfejsie API usługi Azure OpenAI jest użycie klucza interfejsu API. W przypadku tego typu uwierzytelniania wszystkie żądania interfejsu API muszą zawierać prawidłowy klucz interfejsu API w nagłówku api-key HTTP.

  • Usługa API Management może zarządzać kluczem interfejsu API w bezpieczny sposób przy użyciu nazwanej wartości.
  • Nazwana wartość można następnie przywoływać w zasadach interfejsu api-key API, aby ustawić nagłówek w żądaniach na interfejs API usługi Azure OpenAI. Udostępniamy dwa przykłady tego, jak to zrobić: jeden używa set-backend-service zasad, a drugi używa set-header zasad.

Przechowywanie klucza interfejsu API w nazwanej wartości

  1. Uzyskaj klucz interfejsu API z zasobu azure OpenAI. W witrynie Azure Portal znajdź klucz na stronie Klucze i punkt końcowy zasobu Azure OpenAI.
  2. Przejdź do wystąpienia usługi API Management i wybierz pozycję Nazwane wartości w menu po lewej stronie.
  3. Wybierz pozycję + Dodaj i dodaj wartość jako wpis tajny lub opcjonalnie, aby uzyskać więcej zabezpieczeń, użyj odwołania do magazynu kluczy.

Przekazywanie klucza interfejsu API w żądaniach interfejsu API — zasady set-backend-service

  1. Utwórz zaplecze wskazujące interfejs API usługi Azure OpenAI.

    1. W menu po lewej stronie wystąpienia usługi API Management wybierz pozycję Zaplecza.
    2. Wybierz pozycję + Dodaj i wprowadź opisową nazwę zaplecza. Przykład: openai-backend.
    3. W obszarze Typ wybierz pozycję Niestandardowy i wprowadź adres URL punktu końcowego usługi Azure OpenAI. Przykład: https://contoso.openai.azure.com/openai.
    4. W obszarze Poświadczenia autoryzacji wybierz pozycję Nagłówki, a następnie wprowadź ciąg api-key jako nazwę nagłówka i nazwaną wartość jako wartość.
    5. Wybierz pozycję Utwórz.

  2. Dodaj następujący set-backend-service fragment kodu zasad w inbound sekcji zasad, aby przekazać klucz interfejsu API w żądaniach do interfejsu API usługi Azure OpenAI.

    W tym przykładzie zasób zaplecza to openai-backend.

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

Przekazywanie klucza interfejsu API w żądaniach interfejsu API — zasady set-header

Alternatywnie dodaj następujący set-header fragment kodu zasad w inbound sekcji zasad, aby przekazać klucz interfejsu API w żądaniach do interfejsu API Usługi Azure OpenAI. Ten fragment kodu zasad ustawia api-key nagłówek z skonfigurowaną nazwaną wartością.

W tym przykładzie nazwana wartość w usłudze API Management to openai-api-key.

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

Uwierzytelnianie przy użyciu tożsamości zarządzanej

Alternatywny sposób uwierzytelniania w interfejsie API usługi Azure OpenAI przy użyciu tożsamości zarządzanej w usłudze Microsoft Entra ID. Aby uzyskać informacje na temat podstaw, zobacz How to configure Azure OpenAI Service with managed identity (Jak skonfigurować usługę Azure OpenAI Service przy użyciu tożsamości zarządzanej).

Poniżej przedstawiono kroki konfigurowania wystąpienia usługi API Management w celu używania tożsamości zarządzanej do uwierzytelniania żądań w interfejsie API usługi Azure OpenAI.

  1. Włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika dla wystąpienia usługi API Management. W poniższym przykładzie założono, że włączono tożsamość zarządzaną przypisaną przez system wystąpienia.

  2. Przypisz tożsamość zarządzaną rolę użytkownika OpenAI usług Cognitive Services w zakresie do odpowiedniego zasobu. Na przykład przypisz tożsamość zarządzaną przypisaną przez system rolę użytkownika openAI usług Cognitive Services w zasobie Azure OpenAI. Aby uzyskać szczegółowe instrukcje, zobacz Kontrola dostępu oparta na rolach dla usługi Azure OpenAI.

  3. Dodaj następujący fragment kodu zasad w inbound sekcji zasad, aby uwierzytelnić żądania do interfejsu API usługi Azure OpenAI przy użyciu tożsamości zarządzanej.

    W tym przykładzie:

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

Autoryzacja protokołu OAuth 2.0 przy użyciu dostawcy tożsamości

Aby umożliwić bardziej szczegółowe uzyskiwanie dostępu do interfejsów API interfejsów OpenAPI przez określonych użytkowników lub klientów, możesz wstępnie uwierzytelnić dostęp do interfejsu API usługi Azure OpenAI przy użyciu autoryzacji OAuth 2.0 przy użyciu identyfikatora Entra firmy Microsoft lub innego dostawcy tożsamości. Aby uzyskać podstawowe informacje, zobacz Ochrona interfejsu API w usłudze Azure API Management przy użyciu autoryzacji OAuth 2.0 przy użyciu identyfikatora Entra firmy Microsoft.

Uwaga

Użyj autoryzacji OAuth 2.0 w ramach strategii ochrony w głębi systemu. Nie zastępuje uwierzytelniania klucza interfejsu API ani uwierzytelniania tożsamości zarządzanej w interfejsie API usługi Azure OpenAI.

Poniżej przedstawiono ogólne kroki ograniczania dostępu interfejsu API do użytkowników lub aplikacji autoryzowanych przy użyciu dostawcy tożsamości.

  1. Utwórz aplikację u dostawcy tożsamości, aby reprezentować interfejs API OpenAI w usłudze Azure API Management. Jeśli używasz identyfikatora Entra firmy Microsoft, zarejestruj aplikację w dzierżawie microsoft Entra ID. Zarejestruj szczegóły, takie jak identyfikator aplikacji i identyfikator URI odbiorców.

    W razie potrzeby skonfiguruj aplikację tak, aby miała role lub zakresy reprezentujące szczegółowe uprawnienia wymagane do uzyskania dostępu do interfejsu API usługi Azure OpenAI.

  2. inbound Dodaj fragment kodu zasad w wystąpieniu usługi API Management, aby zweryfikować żądania, które przedstawiają token internetowy JSON (JWT) w nagłówkuAuthorization. Umieść ten fragment kodu przed innymi inbound zasadami ustawionymi na uwierzytelnianie w interfejsie API usługi Azure OpenAI.

    Uwaga

    W poniższych przykładach przedstawiono ogólną strukturę zasad w celu zweryfikowania JWT. Dostosuj je do dostawcy tożsamości oraz wymagań aplikacji i interfejsu API.

    • validate-azure-ad-token — jeśli używasz identyfikatora Entra firmy Microsoft, skonfiguruj validate-azure-ad-token zasady w celu zweryfikowania odbiorców i oświadczeń w zestawie JWT. Aby uzyskać szczegółowe informacje, zobacz dokumentację zasad.

      <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 — jeśli używasz innego dostawcy tożsamości, skonfiguruj validate-jwt zasady w celu zweryfikowania odbiorców i oświadczeń w usłudze JWT. Aby uzyskać szczegółowe informacje, zobacz dokumentację zasad.

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

Powiązana zawartość