Проверка подлинности и авторизация доступа к API LLM с помощью службы "Управление API Azure"

ПРИМЕНЯЕТСЯ КО ВСЕМ уровням управления API

Из этой статьи вы узнаете, как пройти проверку подлинности и авторизовать доступ к конечным точкам API ИИ, которым управляет Управление API Azure. В этой статье показаны следующие распространенные методы:

• Аутентификация - Взаимодействие с AI API на основе политик, использующих либо ключ API, либо управляемое удостоверение Microsoft Entra ID.

• Авторизация - Для более точного контроля доступа предварительно авторизуйте запросы, которые передают маркеры OAuth 2.0, созданные поставщиком удостоверений, таким как Microsoft Entra ID.

Для справки см. статью.

• Проверка подлинности к API и авторизация в менеджменте API.

Предпосылки

Чтобы выполнить следующие примеры в этой статье, необходимо:

• Инстанция управления API. См. пример шагов в статье Создание экземпляра управления API Azure.
• Развертывание модели ИИ, добавленное в экземпляр управления API в роли искусственного интеллекта. Например, см. инструкции по импорту API Microsoft Foundry или импорту API языковой модели.
• (Для авторизации OAuth 2.0) Разрешения на создание регистрации приложения в поставщике удостоверений, например клиента идентификатора Microsoft Entra, связанного с подпиской Azure.

Проверка подлинности с помощью ключа API

По умолчанию для проверки подлинности в API ИИ используется ключ API. Для этого типа проверки подлинности все запросы API должны содержать допустимый ключ API в заголовке HTTP. Имя заголовка зависит от API. Например, в API Azure OpenAI в Microsoft Foundry используется заголовок api-key.

• Управление API может управлять ключом API безопасным способом с помощью именованного значения.
• Вы можете ссылаться на именованное значение в политике API, чтобы задать api-key заголовок в запросах к API. В следующих двух примерах показано, как это сделать: одна использует set-backend-service политику, а другая использует set-header политику.

Хранение ключа API в именованном значении

Ниже приведен пример хранения ключа API Azure OpenAI в именованном значении в службе управления API:

1. Получите ключ API из развертывания модели ИИ. Для развертывания модели Azure OpenAI найдите эту информацию на домашней странице проекта на портале Microsoft Foundry.
2. Перейдите к экземпляру управления API и в левом меню выберите Именованные значения.
3. Выберите +Добавить и добавьте значение в виде секрета. Для повышения безопасности при необходимости используйте ссылку на хранилище ключей.

Передача ключа API в запросах к API — политика настройки службы бэкенда.

1. Создайте бэкенд, который указывает на Azure OpenAI API.

   1. В меню слева экземпляра управления API выберите бэкенды.
   2. Выберите +Добавить и введите описательное имя серверной части. Пример: openai-backend.
   3. В разделе " Тип" выберите "Пользовательский" и введите URL-адрес конечной точки Azure OpenAI. Пример: https://contoso.services.ai.azure.com/openai.
   4. В разделе учетные данные авторизации выберите заголовки и введите api-key в качестве имени заголовка и именованное значение в качестве значения.
   5. Нажмите кнопку "Создать".

2. Добавьте следующий set-backend-service фрагмент политики в inbound раздел политики, чтобы передать ключ API в запросах к API OpenAI Azure.

   В этом примере серверный ресурс — это openai-backend.

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

Передача ключа API в запросах API — политика установки заголовков

Кроме того, добавьте следующий set-header фрагмент политики в inbound раздел политики, чтобы передать ключ API в запросах к API Azure OpenAI. Этот фрагмент политики задает api-key заголовок с именованным значением, которое вы установили.

В этом примере именованное значение в Управлении API — openai-api-key.

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

Аутентифицироваться с помощью управляемой идентичности

Для Azure OpenAI и других развертываний моделей в Microsoft Foundry используйте управляемое удостоверение в идентификаторе Microsoft Entra для проверки подлинности. Для справки см. Как настроить Azure OpenAI в моделях Microsoft Foundry с аутентификацией Microsoft Entra ID.

Выполните следующие действия, чтобы настроить экземпляр управления API для использования управляемой идентичности для проверки подлинности.

1. Включите управляемую идентификацию, назначаемую системой или пользователем, для вашего экземпляра API Management. В следующем примере предполагается, что вы включили управляемое удостоверение, назначаемое системой.

2. Назначьте управляемому удостоверению роль пользователя Cognitive Services OpenAI с областью действия, соответствующей ресурсу. Например, назначьте управляемому удостоверению, назначаемому системой, роль Cognitive Services OpenAI User в ресурсе Microsoft Foundry. Подробные инструкции см. в статье "Управление доступом на основе ролей" для службы Azure OpenAI.

3. Добавьте следующий фрагмент политики в inbound раздел политики для проверки подлинности запросов к API с помощью управляемого удостоверения.

   В этом примере:

   • Политика authentication-managed-identity получает токен доступа для управляемого удостоверения.
   • Политика 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> 
   

Авторизация OAuth 2.0 с помощью поставщика удостоверений

Чтобы обеспечить более подробный доступ к Azure OpenAPI или другим API LLM определенными пользователями или клиентами, предварительно выполните предварительную проверку доступа к API с помощью авторизации OAuth 2.0 с помощью идентификатора Microsoft Entra ID или другого поставщика удостоверений. Дополнительные сведения см. в статье "Защита API с помощью службы управления API в Azure и авторизации OAuth 2.0 с помощью Microsoft Entra ID".

Ниже показано, как ограничить доступ к API пользователям или приложениям, авторизованным с помощью поставщика удостоверений.

1. Создайте приложение в поставщике идентификаций, чтобы интегрировать API ИИ в службе управления API Azure. Если вы используете идентификатор Microsoft Entra, зарегистрируйте приложение в клиенте Идентификатора Microsoft Entra ID. Запишите сведения, например, идентификатор приложения и универсальный код ресурса (URI) аудитории.

   При необходимости настройте приложение для получения ролей или областей, представляющих точные разрешения, необходимые для доступа к API ИИ.

2. inbound Добавьте фрагмент политики в экземпляр API Management для проверки запросов, представляющих веб-токен JSON (JWT) в заголовке Authorization. Поместите этот фрагмент перед другими inbound политиками, установленными для проверки подлинности в API OpenAI Azure.

   Замечание

   В следующих примерах показана общая структура политик для проверки JWT. Настройте их под вашего провайдера идентификаций и требования вашего приложения и API.

   • validate-azure-ad-token . Если вы используете идентификатор Microsoft Entra, настройте validate-azure-ad-token политику для проверки аудитории и утверждений в JWT. Дополнительные сведения см. в справочнике по политике.

     <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 — если вы используете другого поставщика удостоверений, настройте validate-jwt политику для валидации аудитории и утверждений в 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 и OAuth2.0.
• Проверка подлинности запросов на средства Foundry