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

DOTYCZY: Wszystkich poziomów zarządzania API

Z tego artykułu dowiesz się, jak uwierzytelniać i autoryzować dostęp do punktów końcowych interfejsu API sztucznej inteligencji zarządzanych przez usługę Azure API Management. W tym artykule przedstawiono następujące typowe metody:

• Uwierzytelnianie — Uwierzytelniaj w interfejsie API sztucznej inteligencji przy użyciu zasad korzystających z klucza API lub zarządzanej tożsamości 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:

• Uwierzytelnianie i autoryzacja interfejsów API w usłudze API Management.

Wymagania wstępne

Aby postępować zgodnie z przykładami w tym artykule, musisz mieć następujące elementy:

• Instancja zarządzania API. Aby uzyskać przykładowe kroki, zobacz Tworzenie instancji usługi Azure API Management.
• Wdrożenie modelu AI dodane do wystąpienia usługi API Management jako sztuczna inteligencja. Aby uzyskać przykładowe kroki, zobacz Importowanie interfejsu API usługi Microsoft Foundry lub Importowanie interfejsu API modelu językowego.
• (W przypadku autoryzacji OAuth 2.0) Uprawnienia do tworzenia rejestracji aplikacji u dostawcy tożsamości, takiego jak dzierżawa identyfikatora Entra firmy Microsoft skojarzonej z subskrypcją platformy Azure.

Uwierzytelnianie za pomocą klucza API

Domyślnym sposobem uwierzytelniania w interfejsie API AI jest użycie klucza API. W przypadku tego typu uwierzytelniania wszystkie żądania interfejsu API muszą zawierać prawidłowy klucz interfejsu API w nagłówku HTTP. Nazwa nagłówka zależy od interfejsu API. Na przykład interfejsy API usługi Azure OpenAI w usłudze Microsoft Foundry używają nagłówka api-key .

• Usługa API Management może zarządzać kluczem interfejsu API w bezpieczny sposób przy użyciu nazwanej wartości.
• Możesz odwołać się do nazwanej wartości w polityce API, aby ustawić nagłówek api-key w żądaniach do tego interfejsu API. W poniższych dwóch przykładach pokazano, jak to zrobić: jeden używa set-backend-service polityki, a drugi używa set-header polityki.

Przechowuj klucz interfejsu API w wartości o nazwie

Oto przykład, jak zapisać klucz interfejsu API Azure OpenAI w nazwanej wartości w Zarządzaniu interfejsami API.

1. Pobierz klucz interfejsu API z wdrożenia modelu AI. W przypadku wdrożenia modelu Usługi Azure OpenAI znajdź te informacje na stronie głównej projektu w portalu Microsoft Foundry.
2. Przejdź do wystąpienia usługi API Management i wybierz pozycję Nazwane wartości w menu po lewej stronie.
3. Wybierz + Dodaj i dodaj wartość jako sekret. Aby uzyskać większe bezpieczeństwo, opcjonalnie użyj odwołania 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.services.ai.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 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

W przypadku wdrożeń usługi Azure OpenAI i innych modeli w rozwiązaniu Microsoft Foundry użyj tożsamości zarządzanej w identyfikatorze Entra firmy Microsoft do uwierzytelniania. Aby uzyskać podstawowe informacje, zobacz Jak skonfigurować usługę Azure OpenAI w modelach rozwiązania Microsoft Foundry przy użyciu uwierzytelniania identyfikatora Entra firmy Microsoft.

Wykonaj następujące kroki, aby skonfigurować wystąpienie usługi API Management do używania tożsamości zarządzanej do uwierzytelniania.

1. Włącz tożsamość zarządzaną przypisaną przez system bądź użytkownika dla instancji usługi API Management. Zakłada się, że w poniższym przykładzie włączono tożsamość zarządzaną przypisaną przez system instancji.

2. Przypisz tożsamości zarządzanej rolę Cognitive Services OpenAI User, przypisaną do odpowiedniego zasobu. Na przykład przypisz tożsamość zarządzaną przypisaną przez system rolę użytkownika OpenAI usług Cognitive Services w zasobie Microsoft Foundry. 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 sekcji zasad, inbound aby uwierzytelnić żądania do interfejsu API przy użyciu tożsamości zarządzanej.

   W tym przykładzie:

   • Zasada authentication-managed-identity uzyskuje token dostępu dla tożsamości zarządzanej.
   • Zasady set-header ustawiają nagłówek Authorization żądania przy użyciu tokenu dostępu.

   <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 interfejsu AZURE OpenAPI lub innych interfejsów API LLM przez określonych użytkowników lub klientów, wstępnie uwierzytelniaj dostęp do interfejsu API przy użyciu 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.

W poniższych krokach pokazano, jak ograniczyć dostęp 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 sztucznej inteligencji 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 sztucznej inteligencji.

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

   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>
     

Treści powiązane

• Dowiedz się więcej o Microsoft Entra ID i OAuth2.0.
• Uwierzytelnianie żądań w narzędziach foundry