Azure API Management를 사용하여 Azure OpenAI API에 대한 액세스 인증 및 권한 부여

적용 대상: 모든 API Management 계층

이 문서에서는 Azure API Management를 사용하여 관리되는 Azure OpenAI API 엔드포인트를 인증하고 권한을 부여하는 방법에 대해 알아봅니다. 이 문서에서는 다음과 같은 일반적인 방법을 보여 줍니다.

• 인증 - API 키 또는 Microsoft Entra ID 관리 ID를 사용하여 인증하는 정책을 사용하여 Azure OpenAI API에 인증합니다.

• 권한 부여 - 더욱 세분화된 액세스 제어를 위해 Microsoft Entra ID와 같은 ID 공급자가 생성한 OAuth 2.0 토큰을 전달하는 요청에 미리 권한 부여합니다.

배경 정보는 다음을 참조하세요.

• Azure OpenAI 서비스 REST API 참조

• API Management의 API에 대한 인증 및 권한 부여.

필수 조건

이 문서의 단계를 수행하기 전에 다음이 필요합니다.

• API Management 인스턴스. 단계 예를 보려면 Azure API Management 인스턴스 만들기를 참조하세요.
• API Management 인스턴스에 추가된 Azure OpenAI 리소스 및 모델입니다. 단계 예를 보려면 Azure OpenAI API를 REST API로 가져오기를 참조하세요.
• Azure 구독과 연결된 Microsoft Entra 테넌트와 같은 ID 공급자에서 앱 등록을 만들 수 있는 권한(OAuth 2.0 권한 부여용)

API 키로 인증

Azure OpenAI API에 인증하는 기본 방법은 API 키를 사용하는 것입니다. 이 인증 형식의 경우 모든 API 요청에는 api-key HTTP 헤더에 유효한 API 키가 포함되어야 합니다.

• API Management는 이름이 지정된 값을 사용하여 안전한 방식으로 API 키를 관리할 수 있습니다.
• 그러면 명명된 값을 API 정책에서 참조하여 Azure OpenAI API에 대한 요청에서 api-key 헤더를 설정할 수 있습니다. 이를 수행하는 방법에 대한 두 가지 예를 제공합니다. 하나는 set-backend-service 정책을 사용하고 다른 하나는 set-header 정책을 사용합니다.

API 키를 명명된 값에 저장

1. Azure OpenAI 리소스에서 API 키를 가져옵니다. Azure Portal에서 Azure OpenAI 리소스의 키 및 엔드포인트 페이지에서 키를 찾습니다.
2. API Management 인스턴스로 이동하여 왼쪽 메뉴에서 이름이 지정된 값을 선택합니다.
3. + 추가를 선택하고 값을 비밀로 추가하거나 선택적으로 보안을 강화하려면 키 자격 증명 모음 참조를 사용합니다.

API 요청에 API 키 전달 - set-backend-service 정책

1. Azure OpenAI API를 가리키는 백 엔드를 만듭니다.

   1. API Management 인스턴스의 왼쪽 메뉴에서 백 엔드를 선택합니다.
   2. + 추가를 선택하고 백 엔드를 설명하는 이름을 입력합니다. 예: openai-backend.
   3. 형식에서 사용자 지정을 선택하고 Azure OpenAI 엔드포인트의 URL을 입력합니다. 예: https://contoso.openai.azure.com/openai
   4. 권한 부여 자격 증명에서 헤더를 선택하고 헤더 이름으로 api-key를 입력하고 값으로 명명된 값을 입력합니다.
   5. 만들기를 실행합니다.

2. Azure OpenAI API에 대한 요청에 API 키를 전달하려면 inbound 정책 섹션에 다음 set-backend-service 정책 코드 조각을 추가합니다.

   이 예에서 백 엔드 리소스는 openai-backend입니다.

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

API 요청에 API 키 전달 - 헤더 설정 정책

또는 inbound 정책 섹션에 다음 set-header 정책 코드 조각을 추가하여 Azure OpenAI API에 대한 요청에 API 키를 전달합니다. 이 정책 코드 조각은 사용자가 설정한 명명된 값으로 api-key 헤더를 설정합니다.

이 예에서 API Management의 명명된 값은 openai-api-key입니다.

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

관리 ID를 사용하여 인증

Microsoft Entra ID의 관리 ID를 사용하여 Azure OpenAI API에 인증하는 대체 방법입니다. 백그라운드 지식은 관리 ID로 Azure OpenAI Service를 구성하는 방법을 참조하세요.

다음은 관리 ID를 사용하여 Azure OpenAI API에 대한 요청을 인증하도록 API Management 인스턴스를 구성하는 단계입니다.

1. API Management 인스턴스에 대해 시스템 할당 또는 사용자 할당 관리 ID를 사용하도록 설정합니다. 다음 예에서는 인스턴스의 시스템 할당 관리 ID를 사용하도록 설정했다고 가정합니다.

2. 적절한 리소스로 범위가 할당된 관리 ID에 Cognitive Services OpenAI 사용자 역할을 할당합니다. 예를 들어, 시스템 할당 관리 ID에 Azure OpenAI 리소스의 Cognitive Services OpenAI 사용자 역할을 할당합니다. 자세한 단계는 Azure OpenAI 서비스에 대한 역할 기반 액세스 제어를 참조하세요.

3. 관리 ID를 사용하여 Azure OpenAI API에 대한 요청을 인증하려면 inbound 정책 섹션에 다음 정책 코드 조각을 추가합니다.

   이 예에서는 다음이 적용됩니다.

   • authentication-managed-identity 정책은 관리 ID에 대한 액세스 토큰을 가져옵니다.
   • set-header 정책은 액세스 토큰을 사용하여 요청의 Authorization 헤더를 설정합니다.

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

ID 공급자를 사용한 OAuth 2.0 권한 부여

특정 사용자 또는 클라이언트가 OpenAPI API에 더욱 세밀하게 액세스할 수 있도록 하려면 Microsoft Entra ID 또는 다른 ID 공급자를 통한 OAuth 2.0 권한 부여를 사용하여 Azure OpenAI API에 대한 액세스에 미리 권한 부여할 수 있습니다. 백그라운드 지식은 Microsoft Entra ID로 OAuth 2.0 권한 부여를 사용하여 Azure API Management에서 API 보호를 참조하세요.

참고 항목

심층 방어 전략의 일부로 OAuth 2.0 권한 부여를 사용합니다. Azure OpenAI API에 대한 API 키 인증 또는 관리 ID 인증을 바꾸지 않습니다.

다음은 ID 공급자를 사용하여 권한이 있는 사용자 또는 앱으로 API 액세스를 제한하는 상위 수준 단계입니다.

1. Azure API Management에서 OpenAI API를 나타내기 위해 ID 공급자에 애플리케이션을 만듭니다. Microsoft Entra ID를 사용하는 경우 Microsoft Entra ID 테넌트에 애플리케이션을 등록합니다. 애플리케이션 ID, 대상 그룹 URI 등의 세부 정보를 기록합니다.

   필요에 따라 Azure OpenAI API에 액세스하는 데 필요한 세분화된 권한을 나타내는 역할 또는 범위를 갖도록 애플리케이션을 구성합니다.

2. API Management 인스턴스에 inbound 정책 코드 조각을 추가하여 Authorization 헤더에 JWT(JSON 웹 토큰)를 제공하는 요청의 유효성을 검사합니다. Azure OpenAI API에 인증하기 위해 설정한 다른 inbound 정책 앞에 이 코드 조각을 배치합니다.

   참고 항목

   다음 예에서는 JWT의 유효성을 검사하기 위한 정책의 일반적인 구조를 보여 줍니다. ID 공급자와 애플리케이션 및 API 요구 사항에 맞게 사용자 지정합니다.

   • validate-azure-ad-token - Microsoft Entra ID를 사용하는 경우 JWT에서 대상 그룹 및 클레임의 유효성을 검사하도록 validate-azure-ad-token 정책을 구성합니다. 자세한 내용은 정책 참조를 확인합니다.

     <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 - 다른 ID 공급자를 사용하는 경우 JWT의 대상 그룹 및 소유권의 유효성을 검사하도록 validate-jwt 정책을 구성합니다. 자세한 내용은 정책 참조를 확인합니다.

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

관련 콘텐츠

• Microsoft Entra ID 및 OAuth2.0에 대해 자세히 알아봅니다.
• Azure AI 서비스에 대한 요청 인증
• API Management로 Azure OpenAI 키 보호