Проверка подлинности запросов к службам ИИ Azure

Каждый запрос к службе ИИ Azure должен содержать заголовок проверки подлинности. Этот заголовок передает ключ ресурса или маркер проверки подлинности, который используется для проверки подписки на службу или группу служб. В этой статье вы получите сведения о трех методах проверки подлинности запроса и требованиях для каждого из них.

• Проверка подлинности с помощью ключа ресурса с одним или несколькими службами
• Проверка подлинности по маркеру
• Проверка подлинности с помощью идентификатора Microsoft Entra

Необходимые компоненты

Прежде чем запросить запрос, вам потребуется учетная запись Azure и подписка на службы искусственного интеллекта Azure. Если у вас есть учетная запись, пропустите этот раздел и перейдите к следующему. Если у вас нет учетной записи, у нас есть руководство по настройке в минутах: создание ресурса служб ИИ Azure.

Перейдите к своему ресурсу на портале Azure. Раздел "Ключи и конечная точка " можно найти в разделе "Управление ресурсами". Скопируйте конечную точку и ключ доступа, так как они потребуются для проверки подлинности вызовов API. Вы можете использовать KEY1 или KEY2. Наличие двух ключей позволяет безопасно менять и повторно создавать ключи без прерывания работы службы.

Заголовки проверки подлинности

Давайте быстро рассмотрим заголовки проверки подлинности, доступные для использования со службами ИИ Azure.

Верхний колонтитул	Description
Ocp-Apim-Subscription-Key	Используйте этот заголовок для проверки подлинности с помощью ключа ресурса для определенной службы или ключа ресурса с несколькими службами.
Ocp-Apim-Subscription-Region	Этот заголовок требуется только при использовании ключа ресурса с несколькими службами с помощью службы Azure AI Translator. Используйте этот заголовок, чтобы указать регион ресурса.
Авторизация	Используйте этот заголовок, если вы применяете маркер доступа. В следующих разделах подробно описан процесс обмена маркерами. Значение предоставляется в следующем формате: Bearer <TOKEN>.

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

Первым вариантом является проверка подлинности запроса с помощью ключа ресурса для конкретной службы, например Azure AI Translator. Ключи можно получить на портале Azure для каждого созданного ресурса. Перейдите к своему ресурсу на портале Azure. Раздел "Ключи и конечная точка " можно найти в разделе "Управление ресурсами". Скопируйте конечную точку и ключ доступа, так как они потребуются для проверки подлинности вызовов API. Вы можете использовать KEY1 или KEY2. Наличие двух ключей позволяет безопасно менять и повторно создавать ключи без прерывания работы службы.

Чтобы использовать ключ ресурса для проверки подлинности запроса, его необходимо передать в качестве заголовка Ocp-Apim-Subscription-Key . Это пример вызова службы Azure AI Translator:

Это пример вызова службы перевода текстов:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

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

Для проверки подлинности запросов можно использовать ключ ресурса с несколькими службами . Основное различие заключается в том, что ключ ресурсов с несколькими службами не привязан к определенной службе, а один ключ можно использовать для проверки подлинности запросов для нескольких служб ИИ Azure. Сведения о региональной доступности, поддерживаемых функциях и ценах см . в ценах на службы ИИ Azure.

Ключ ресурса предоставляется в каждом запросе в качестве заголовка Ocp-Apim-Subscription-Key .

Поддерживаемые регионы

При использовании ключа ресурса служб ИИ Azure для выполнения запроса api.cognitive.microsoft.comнеобходимо включить регион в URL-адрес. Например: westus.api.cognitive.microsoft.com.

При использовании ключа ресурса с несколькими службами с Azure AI Translator необходимо указать регион ресурсов с заголовком Ocp-Apim-Subscription-Region .

Многослужбная проверка подлинности ресурсов поддерживается в следующих регионах:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

Примеры запросов

Это пример вызова службы Azure AI Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

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

Некоторые службы ИИ Azure принимают и в некоторых случаях требуют маркера доступа. В настоящее время маркеры доступа поддерживаются в следующих службах:

• API перевода текстов;
• Службы речи: API преобразования речи в текст
• Службы распознавания речи: API преобразования текста в речь

Предупреждение

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

Ключи ресурсов для одной службы и нескольких служб можно обменять на маркеры проверки подлинности. Маркер проверки подлинности действует в течение 10 минут. Они хранятся в формате JSON Web Token (JWT) и могут запрашиваться программным способом с помощью библиотек JWT.

Маркеры доступа добавляются в запрос в заголовке Authorization. К значению маркера следует добавить префикс Bearer, например так: Bearer YOUR_AUTH_TOKEN.

Примеры запросов

Используйте этот URL-адрес для обмена ключом ресурса для маркера доступа: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Обмен маркерами поддерживается в следующих регионах с несколькими службами:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

Получив маркер доступа, его следует включать в каждый запрос в заголовке Authorization. Это пример вызова службы Azure AI Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Проверка подлинности в Microsoft Entra ID

Внимание

Проверка подлинности Microsoft Entra всегда должна использоваться вместе с пользовательским именем поддомена ресурса Azure. Региональные конечные точки не поддерживают проверку подлинности Microsoft Entra.

В предыдущих разделах мы показали, как пройти проверку подлинности в службах ИИ Azure с помощью ключа подписки с одним или несколькими службами. Хотя эти ключи предоставляют быстрый и простой путь начала разработки, они не работают в более сложных сценариях, требующих управления доступом на основе ролей Azure (Azure RBAC). Давайте рассмотрим, что необходимо для проверки подлинности с помощью идентификатора Microsoft Entra.

В следующих разделах вы будете использовать среду Azure Cloud Shell или Azure CLI для создания поддомена, назначения ролей и получения маркера носителя для вызова служб ИИ Azure. На всякий случай в каждом разделе приведены ссылки со всеми доступными параметрами для каждой команды в Azure Cloud Shell и Azure CLI.

Внимание

Если ваша организация выполняет проверку подлинности с помощью идентификатора Microsoft Entra, следует отключить локальную проверку подлинности (проверку подлинности с ключами), чтобы пользователи в организации всегда должны использовать идентификатор Microsoft Entra.

Создание ресурса с пользовательским поддоменом

Сначала нужно создать пользовательский поддомен. Если вы хотите использовать существующий ресурс служб искусственного интеллекта Azure, который не имеет пользовательского имени поддомена, следуйте инструкциям в пользовательских поддоменах служб ИИ Azure, чтобы включить настраиваемый поддомен для ресурса.

1. Для начала откройте среду Azure Cloud Shell. Затем выберите подписку:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Затем создайте ресурс служб ИИ Azure с пользовательским поддоменом. Имя поддомена должно быть глобально уникальным и не может содержать специальные символы, например ".", "!", ",".

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

3. В случае успеха Конечная точка должна показать имя поддомена, уникальное для вашего ресурса.

Назначение роли субъекту-службе.

Теперь, когда есть пользовательский поддомен, связанный с ресурсом, необходимо назначить роль субъекту-службе.

Примечание.

Имейте в виду, что назначение ролей Azure может занять до пяти минут.

1. Сначала зарегистрируйте приложение Microsoft Entra.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   Идентификатор приложения ApplicationId потребуется на следующем шаге.

2. Затем необходимо создать субъект-службу для приложения Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Примечание.

   При регистрации приложения на портал Azure этот шаг выполняется порталом.

3. Последним шагом является назначение роли "Пользователь Cognitive Services" субъекту-службе (в области действия ресурса). Назначая роль, вы предоставляете субъекту-службе доступ к этому ресурсу. Одному субъекту-службе можно предоставить доступ к нескольким ресурсам в своей подписке.

   Примечание.

   Используется ObjectId субъекта-службы, а не ObjectId для приложения. ACCOUNT_ID будет идентификатором ресурса Azure созданной учетной записи служб искусственного интеллекта Azure. Идентификатор ресурса Azure можно найти в "свойствах" ресурса на портале Azure.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

Образец запроса

В этом примере для проверки подлинности субъекта-службы используется пароль. Затем предоставленный маркер используется для вызова API компьютерного зрения.

1. Получите свой идентификатор TenantId:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. Получите маркер:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   Примечание.

   В любой момент, когда вы используете пароли в скрипте, наиболее безопасным вариантом является использование модуля управления секретами PowerShell и интеграция с решением, таким как Azure Key Vault.

3. Вызовите API компьютерного зрения:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

Либо можно проверить подлинность субъекта-службы с помощью сертификата. Кроме субъекта-службы, субъект-пользователь также поддерживается путем делегирования разрешений через другое приложение Microsoft Entra. В этом случае вместо паролей или сертификатов пользователям будет предложено использовать двухфакторную проверку подлинности при получении маркера.

Авторизация доступа к управляемым удостоверениям

Службы искусственного интеллекта Azure поддерживают проверку подлинности Microsoft Entra с управляемыми удостоверениями для ресурсов Azure. Управляемые удостоверения для ресурсов Azure могут авторизовать доступ к ресурсам служб ИИ Azure с помощью учетных данных Microsoft Entra из приложений, работающих на виртуальных машинах Azure, приложениях-функциях, масштабируемых наборах виртуальных машин и других службах. Используя управляемые удостоверения для ресурсов Azure вместе с проверкой подлинности Microsoft Entra, вы можете избежать хранения учетных данных с приложениями, работающими в облаке.

Включение управляемых удостоверений на виртуальной машине

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

• Портал Azure
• Azure PowerShell
• Azure CLI
• Шаблон Azure Resource Manager
• Клиентские библиотеки Azure Resource Manager

Дополнительные сведения об управляемых удостоверениях см. в статье Управляемые удостоверения для ресурсов Azure.

Использование Azure Key Vault для безопасного хранения учетных данных

Azure Key Vault можно использовать для безопасной разработки приложений служб ИИ Azure. Key Vault позволяет хранить учетные данные проверки подлинности в облаке и снижает вероятность случайной утечки секретов, так как вы не будете хранить сведения о безопасности в приложении.

Проверка подлинности выполняется с помощью идентификатора Microsoft Entra. Авторизацию можно выполнить с помощью управления доступом на основе ролей в Azure (Azure RBAC) или политики доступа Key Vault. Azure RBAC можно использовать как для управления хранилищами, так и для доступа к хранимым в них данным. При этом политика доступа к хранилищу ключей может использоваться только при попытке получить доступ к данным в хранилище.

См. также

• Что такое службы ИИ Azure?
• Цены на службы искусственного интеллекта Azure
• Пользовательские поддомены