Проверка подлинности запросов к службам ИИ 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 всегда должна использоваться вместе с пользовательским именем поддомена ресурса 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, чтобы включить настраиваемый поддомен для ресурса.
Для начала откройте среду Azure Cloud Shell. Затем выберите подписку:
Set-AzContext -SubscriptionName <SubscriptionName>
Затем создайте ресурс служб ИИ Azure с пользовательским поддоменом. Имя поддомена должно быть глобально уникальным и не может содержать специальные символы, например ".", "!", ",".
$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
В случае успеха Конечная точка должна показать имя поддомена, уникальное для вашего ресурса.
Теперь, когда есть пользовательский поддомен, связанный с ресурсом, необходимо назначить роль субъекту-службе.
Примечание
Имейте в виду, что назначение ролей Azure может занять до пяти минут.
Сначала зарегистрируйте приложение Microsoft Entra.
$SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
Идентификатор приложения ApplicationId потребуется на следующем шаге.
Затем необходимо создать субъект-службу для приложения Microsoft Entra.
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
Примечание
При регистрации приложения на портал Azure этот шаг выполняется порталом.
Последним шагом является назначение роли "Пользователь Cognitive Services" субъекту-службе (в области действия ресурса). Назначая роль, вы предоставляете субъекту-службе доступ к этому ресурсу. Одному субъекту-службе можно предоставить доступ к нескольким ресурсам в своей подписке.
Примечание
Используется ObjectId субъекта-службы, а не ObjectId для приложения. ACCOUNT_ID будет идентификатором ресурса Azure созданной учетной записи служб искусственного интеллекта Azure. Идентификатор ресурса Azure можно найти в "свойствах" ресурса на портале Azure.
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
В этом примере для проверки подлинности субъекта-службы используется пароль. Затем предоставленный маркер используется для вызова API компьютерного зрения.
Получите свой идентификатор TenantId:
$context=Get-AzContext $context.Tenant.Id
Получите маркер:
$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.
Вызовите 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 позволяет хранить учетные данные проверки подлинности в облаке и снижает вероятность случайной утечки секретов, так как вы не будете хранить сведения о безопасности в приложении.
Проверка подлинности выполняется с помощью идентификатора Microsoft Entra. Авторизацию можно выполнить с помощью управления доступом на основе ролей в Azure (Azure RBAC) или политики доступа Key Vault. Azure RBAC можно использовать как для управления хранилищами, так и для доступа к хранимым в них данным. При этом политика доступа к хранилищу ключей может использоваться только при попытке получить доступ к данным в хранилище.