Udostępnij za pomocą

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

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 – Uwierzytelnij się w usłudze Azure OpenAI API, korzystając z zasad uwierzytelniania za pomocą klucza API lub tożsamości zarządzanej przez Microsoft Entra ID.

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

Uwierzytelnij za pomocą klucza 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.
  • Nazwaną wartość można następnie przywoływać w zasadach polityki API api-key, aby umożliwić ustawianie nagłówka w żądaniach do interfejsu API 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.

Przechowuj klucz interfejsu API w wartości o nazwie

  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 tajny, lub opcjonalnie, aby uzyskać więcej zabezpieczeń, użyj referencji do magazynu kluczy.

Przekaż klucz API w żądaniach API — polityka ustawień usługi backendowej

  1. Utwórz backend wskazujący na API Azure OpenAI.

    1. W menu po lewej stronie wystąpienia usługi API Management wybierz pozycję Zaplecza.
    2. Wybierz + Dodaj i wprowadź opisową nazwę dla backendu. 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 Nagłówki, a następnie wprowadź 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 API w żądaniach do API Azure OpenAI.

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

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

Przekazywanie klucza API w żądaniach API — zasady ustawiania nagłówków

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

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

Alternatywnym i zalecanym sposobem uwierzytelniania w interfejsie API usługi Azure OpenAI jest użycie 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 bądź użytkownika dla instancji usługi API Management. W poniższym przykładzie założono, że włączono zarządzaną tożsamość przypisaną przez system wystąpienia.

  2. Przypisz tożsamości zarządzanej rolę Cognitive Services OpenAI User, przypisaną do odpowiedniego zasobu. Na przykład przypisz zarządzaną przez system tożsamość z rolą użytkownika OpenAI w usługach 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>

Wskazówka

Alternatywą dla użycia authentication-managed-identity zasad i set-header pokazanych w tym przykładzie jest skonfigurowanie zasobu zaplecza , który kieruje żądania interfejsu API do punktu końcowego usługi Azure OpenAI Service. W konfiguracji zaplecza włącz uwierzytelnianie tożsamości zarządzanej w usłudze Azure OpenAI Service. Usługa Azure API Management automatyzuje te kroki podczas importowania interfejsu API bezpośrednio z usługi Azure OpenAI Service. Aby uzyskać więcej informacji, zobacz Importowanie interfejsu API z usługi Azure OpenAI Service.

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

Aby umożliwić bardziej szczegółowy dostęp do interfejsów API OpenAPI przez określonych użytkowników lub klientów, możesz wstępnie uwierzytelnić dostęp do interfejsu API usługi Azure OpenAI, używając autoryzacji OAuth 2.0 za pomocą 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 dla interfejsu API 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 Microsoft Entra ID, 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 Microsoft Entra ID, skonfiguruj validate-azure-ad-token politykę w celu zweryfikowania odbiorców i oświadczeń w JWT. Aby uzyskać szczegółowe informacje, zobacz odniesienie do 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 odniesienie do 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ść

  • Last updated on