Настройка проверки подлинности без ключей с помощью Microsoft Entra ID

В этой статье объясняется, как настроить проверку подлинности без ключей с помощью Microsoft Entra ID для моделей Microsoft Foundry. Проверка подлинности без ключей повышает безопасность, устраняя необходимость ключей API, упрощает взаимодействие с пользователем с помощью управления доступом на основе ролей (RBAC) и снижает операционную сложность, обеспечивая надежную поддержку соответствия требованиям.

Необходимые условия

Чтобы завершить эту статью, вам потребуется:

Необходимые Azure роли и разрешения

Microsoft Entra ID использует управление доступом на основе ролей (RBAC) для управления доступом к ресурсам Azure. Вам нужны разные роли в зависимости от того, настраиваете ли вы проверку подлинности (администратор) или используете ее для вызова API (разработчика).

Настройка проверки подлинности

  • Владелец или администратор подписки: учетная запись с разрешениями Microsoft.Authorization/roleAssignments/write и Microsoft.Authorization/roleAssignments/delete, например, роль владельца или администратора доступа пользователей, необходимая для назначения роли пользователя Cognitive Services разработчикам.

Для выполнения вызовов API с проверкой подлинности

  • роль пользователя Cognitive Services. Требуется для разработчиков для проверки подлинности и выполнения вызовов API вывода с помощью Microsoft Entra ID. Эта роль должна быть назначена на уровне ресурса Foundry.

Требования к назначению ролей

При назначении ролей укажите следующие три элемента:

  • Субъект безопасности: учетная запись пользователя, сервисный субъект или группа безопасности (рекомендуется для управления несколькими пользователями)
  • Определение роли: роль пользователя Cognitive Services
  • Область: ваш конкретный ресурс Foundry

Совет

Назначения ролей в Azure могут занимать до 5 минут на распространение. При использовании групп безопасности изменения членства в группах распространяются немедленно.

Настраиваемая роль (необязательно)

Если вы предпочитаете пользовательскую роль вместо Cognitive Services User, убедитесь, что она включает следующие разрешения:

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}

Для получения дополнительной информации о том, как роли работают с ресурсами Azure, ознакомьтесь с Понимание ролей в контексте ресурсов в Azure.

Настройка Microsoft Entra ID для анализа

В этом разделе перечислены шаги по настройке Microsoft Entra ID для вывода на странице ресурсов Microsoft Foundry на портале Azure.

Снимок экрана, показывающий ресурс, для которого мы настраиваем Microsoft Entra ID.

  1. Выберите имя ресурса, чтобы открыть его.

  2. В левой области выберите элемент управления доступом (IAM); затем выберите Добавить> и назначить роль.

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

    Совет

    Используйте параметр "Просмотреть мой доступ" , чтобы проверить, какие роли уже назначены вам.

  3. В поле Роли функций задания введите Пользователь когнитивных служб.

    Снимок экрана, показывающий процесс выбора назначения роли пользователя Cognitive Services.

  4. Выберите роль и нажмите кнопку "Далее".

  5. На вкладке "Участники" выберите пользователя или группу, к которой вы хотите предоставить доступ. Используйте группы безопасности по возможности, так как они проще управлять и поддерживать.

    Снимок экрана: выбор пользователя, которому назначена роль.

  6. Нажмите кнопку "Далее " и завершите работу мастера.

  7. Выбранный пользователь теперь может использовать Microsoft Entra ID для вывода.

    Совет

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

  8. Проверьте назначение роли:

    1. На левой панели в портале Azure выберите элемент управления Управление доступом (IAM).

    2. Выберите "Проверить доступ".

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

    4. Убедитесь, что Cognitive Services User отображается в назначенных ролях.

Доступ на основе ключей по-прежнему возможен для пользователей, у которых уже есть ключи. Чтобы отозвать ключи на портале Azure, на левой панели навигации выберите Resource Management>Keys and Endpoints>Regenerate Key1 и Regenerate Key2.

Используйте Microsoft Entra ID в своем коде

После настройки Microsoft Entra ID в ресурсе обновите код, чтобы он использовался при обращении к конечной точке предсказаний. В этом примере показано, как использовать модель завершения чата:

Установите пакет SDK OpenAI с помощью диспетчера пакетов, например pip:

pip install openai

Для проверки подлинности Microsoft Entra ID также установите следующее:

pip install azure-identity

Используйте пакет для работы с моделью. В следующем примере показано, как создать клиента для потребления завершения чата с Microsoft Entra ID и выполнить тестовый запрос к конечной точке завершения чата, используя развернутую модель.

Замените <resource> именем вашего ресурса Foundry. Найдите его на портале Azure или запустив az cognitiveservices account list. Замените DeepSeek-V3.1 фактическим именем развертывания.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Ожидаемые выходные данные

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Справочные материалы: OpenAI Python SDK и DefaultAzureCredential class.

Параметры идентификации при использовании Microsoft Entra ID

DefaultAzureCredential является упорядоченной последовательностью механизмов с заданной конфигурацией для аутентификации в Microsoft Entra ID. Каждый механизм проверки подлинности — это класс, производный от TokenCredential класса и известный как учетные данные. Во время выполнения DefaultAzureCredential пытается пройти проверку подлинности с помощью первых учетных данных. Если этой учетной записи не удается получить токен доступа, пробуется следующая учетная запись в последовательности, и так далее, до получения токена доступа. Таким образом, приложение может использовать разные учетные данные в разных средах без написания кода для конкретной среды.

Когда предыдущий код выполняется на локальной рабочей станции разработки, он выглядит в переменных среды для субъекта-службы приложений или локально установленных средств разработчика, например Visual Studio, для набора учетных данных разработчика. Вы можете использовать любой подход для проверки подлинности приложения для Azure ресурсов во время локальной разработки.

При развертывании в Azure этот же код также может пройти проверку подлинности приложения в других Azure ресурсах. DefaultAzureCredential может получать параметры среды и конфигурации управляемой идентичности для автоматической аутентификации в других службах.

Лучшие практики

  • Используйте детерминированные аутентификационные данные в производственных средах: настоятельно рекомендуется серьезно рассмотреть возможность перехода от использования DefaultAzureCredential к одному из следующих детерминированных решений в производственных средах.

    • Конкретная TokenCredential реализация, например ManagedIdentityCredential. См. список производных параметров.
    • Упрощенная реализация ChainedTokenCredential, оптимизированная для среды Azure, в которой выполняется ваше приложение. ChainedTokenCredential по существу создает определенный список допустимых параметров учетных данных, например ManagedIdentity для рабочей среды и VisualStudioCredential разработки.

  • Если возможно, настройте управляемые удостоверения, назначаемые системой или пользователем, для ресурсов Azure, где выполняется ваш код. Настройте доступ Microsoft Entra ID к определенным учетным записям.

Отключение проверки подлинности на основе ключей в ресурсе

Отключите проверку подлинности на основе ключей при внедрении Microsoft Entra ID и полностью устраните проблемы совместимости или варианты отката во всех приложениях, использующих эту службу. Проверку подлинности на основе ключей можно отключить с помощью Azure CLI или при развертывании с помощью Bicep или ARM.

Доступ на основе ключей по-прежнему возможен для пользователей, у которых уже есть ключи. Чтобы отозвать ключи на портале Azure, на левой панели навигации выберите Resource Management>Keys and Endpoints>Regenerate Key1 и Regenerate Key2.

  • Установите Azure CLI

  • Определите следующие сведения:

    • Идентификатор подписки Azure

    • Имя ресурса Microsoft Foundry

    • Группа ресурсов, в которой развернут ресурс Foundry

Настройка Microsoft Entra ID для анализа

Чтобы настроить Microsoft Entra ID для вывода, выполните следующие действия.

  1. Войдите в подписку Azure.

    # Authenticate with Azure and sign in interactively
az login

  2. Если у вас несколько подписок, выберите подписку, в которой находится ваш ресурс.

    # Set the active subscription context
az account set --subscription "<subscription-id>"

  3. Задайте следующие переменные среды с именем ресурса и группы ресурсов, которые вы планируете использовать.

    # Store resource identifiers for reuse in subsequent commands
ACCOUNT_NAME="<ai-services-resource-name>"
RESOURCE_GROUP="<resource-group>"

  4. Получите полное наименование вашего ресурса.

    # Retrieve the full Azure Resource Manager ID for role assignment scoping
RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts" --query id --output tsv)

  5. Получите идентификатор объекта субъекта безопасности, которому требуется назначить разрешения. В следующих примерах показано, как получить идентификатор объекта, связанный с:

    Ваша собственная учетная запись для входа:

    # Get your user's Microsoft Entra ID object ID
OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)

    Группа безопасности:

    # Get the object ID for a security group (recommended for production)
OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)

    Сервисный принципал:

    # Get the object ID for a service principal (for app authentication)
OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)

  6. Назначьте роль пользователя Cognitive Services основной службе (в пределах ресурса). Назначая роль, вы предоставляете субъекту-службе доступ к этому ресурсу.

    # Grant inference access by assigning the Cognitive Services User role
az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID

  7. Выбранный пользователь теперь может использовать Microsoft Entra ID для вывода.

    Совет

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

  8. Проверьте назначение роли:

    az role assignment list --scope $RESOURCE_ID --assignee $OBJECT_ID --query "[?roleDefinitionName=='Cognitive Services User'].{principalName:principalName, roleDefinitionName:roleDefinitionName}" --output table

    Выходные данные должны показывать назначенную вашему субъекту роль пользователя Cognitive Services.

Используйте Microsoft Entra ID в своем коде

После настройки Microsoft Entra ID в ресурсе обновите код, чтобы он использовался при обращении к конечной точке предсказаний. В следующем примере показано, как использовать модель завершения чата:

Установите пакет SDK OpenAI с помощью диспетчера пакетов, например pip:

pip install openai

Для проверки подлинности Microsoft Entra ID также установите следующее:

pip install azure-identity

Используйте пакет для работы с моделью. В следующем примере показано, как создать клиента для потребления завершения чата с Microsoft Entra ID и выполнить тестовый запрос к конечной точке завершения чата, используя развернутую модель.

Замените <resource> именем вашего ресурса Foundry. Найдите его на портале Azure или запустив az cognitiveservices account list. Замените DeepSeek-V3.1 фактическим именем развертывания.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Ожидаемые выходные данные

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Справочные материалы: OpenAI Python SDK и DefaultAzureCredential class.

Параметры идентификации при использовании Microsoft Entra ID

DefaultAzureCredential является упорядоченной последовательностью механизмов с заданной конфигурацией для аутентификации в Microsoft Entra ID. Каждый механизм проверки подлинности — это класс, производный от TokenCredential класса и известный как учетные данные. Во время выполнения DefaultAzureCredential пытается пройти проверку подлинности с помощью первых учетных данных. Если этой учетной записи не удается получить токен доступа, пробуется следующая учетная запись в последовательности, и так далее, до получения токена доступа. Таким образом, приложение может использовать разные учетные данные в разных средах без написания кода для конкретной среды.

Когда предыдущий код выполняется на локальной рабочей станции разработки, он выглядит в переменных среды для субъекта-службы приложений или локально установленных средств разработчика, например Visual Studio, для набора учетных данных разработчика. Вы можете использовать любой подход для проверки подлинности приложения для Azure ресурсов во время локальной разработки.

При развертывании в Azure этот же код также может пройти проверку подлинности приложения в других Azure ресурсах. DefaultAzureCredential может получать параметры среды и конфигурации управляемой идентичности для автоматической аутентификации в других службах.

Лучшие практики

  • Используйте детерминированные аутентификационные данные в производственных средах: настоятельно рекомендуется серьезно рассмотреть возможность перехода от использования DefaultAzureCredential к одному из следующих детерминированных решений в производственных средах.

    • Конкретная TokenCredential реализация, например ManagedIdentityCredential. См. список производных параметров.
    • Упрощенная реализация ChainedTokenCredential, оптимизированная для среды Azure, в которой выполняется ваше приложение. ChainedTokenCredential по существу создает определенный список допустимых параметров учетных данных, например ManagedIdentity для рабочей среды и VisualStudioCredential разработки.

  • Если возможно, настройте управляемые удостоверения, назначаемые системой или пользователем, для ресурсов Azure, где выполняется ваш код. Настройте доступ Microsoft Entra ID к определенным учетным записям.

Отключение проверки подлинности на основе ключей в ресурсе

Отключите проверку подлинности на основе ключей при внедрении Microsoft Entra ID и полностью устраните проблемы совместимости или резервные варианты во всех приложениях, использующих эту службу. Используйте PowerShell с Azure CLI, чтобы отключить локальную проверку подлинности для отдельного ресурса. Сначала войдите с помощью Connect-AzAccount команды. Затем используйте Set-AzCognitiveServicesAccount командлет с параметром -DisableLocalAuth $true, как показано в следующем примере:

Set-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name" -DisableLocalAuth $true

Дополнительные сведения об использовании Azure CLI для отключения или повторной проверки локальной проверки подлинности и проверки состояния проверки подлинности см. в статье Disable local authentication in Foundry Tools.

  • Установите Azure CLI

  • Определите следующие сведения:

    • Идентификатор подписки Azure

Об этом руководстве

Пример в этой статье основан на примерах кода в репозитории Azure-Samples/azureai-model-inference-bicep. Чтобы выполнить команды локально без копирования или вставки содержимого файла, клонируйте репозиторий с помощью этих команд и перейдите в папку для языка программирования:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

Файлы для этого примера находятся в следующем каталоге:

cd azureai-model-inference-bicep/infra

Общие сведения о ресурсах

В этом руководстве вы создадите следующие ресурсы:

  • Ресурс Microsoft Foundry с отключенным доступом к ключу. Для простоты этот шаблон не развертывает модели.
  • Назначение ролей для заданного субъекта безопасности с ролью "Пользователь Cognitive Services".

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

  1. Используйте шаблон modules/ai-services-template.bicep для описания ресурса Foundry.

    modules/ai-services-template.bicep

    @description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

    Совет

    Этот шаблон принимает allowKeys параметр. Установите значение false, чтобы отключить доступ к ключу в ресурсе.

  2. Используйте шаблон modules/role-assignment-template.bicep, чтобы описать назначение роли в Azure:

    modules/role-assignment-template.bicep

    @description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionID string

@description('Specifies the principal ID assigned to the role.')
param principalId string

@description('Specifies the resource ID of the resource to assign the role to.')
param scopeResourceId string = resourceGroup().id

var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
    principalId: principalId
  }
}

output name string = roleAssignment.name
output resourceId string = roleAssignment.id

Создание ресурсов

В консоли выполните следующие действия.

  1. Определите основное развертывание:

    deploy-entra-id.bicep

    @description('Location to create the resources in')
param location string = resourceGroup().location

@description('Name of the resource group to create the resources in')
param resourceGroupName string = resourceGroup().name

@description('Name of the AI Services account to create')
param accountName string = 'azurei-models-dev'

@description('ID of the developers to assign the user role to')
param securityPrincipalId string

module aiServicesAccount 'modules/ai-services-template.bicep' = {
  name: 'aiServicesAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    accountName: accountName
    location: location
    allowKeys: false
  }
}

module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
  name: 'roleAssignmentDeveloperAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
    principalId: securityPrincipalId
  }
}

output endpoint string = aiServicesAccount.outputs.endpointUri

  2. Войдите в Azure:

    az login

  3. Убедитесь, что вы находитесь в правильной подписке:

    az account set --subscription "<subscription-id>"

  4. Запустите развертывание:

    RESOURCE_GROUP="<resource-group-name>"
SECURITY_PRINCIPAL_ID="<your-security-principal-id>"

az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --parameters securityPrincipalId=$SECURITY_PRINCIPAL_ID \
  --template-file deploy-entra-id.bicep

  5. Шаблон выводит конечную точку Foundry Models, которую можно использовать для доступа к любому из созданных развертываний модели.

  6. Проверьте развертывание и назначение ролей:

    # Get the endpoint from deployment output
ENDPOINT=$(az deployment group show --resource-group $RESOURCE_GROUP --name deploy-entra-id --query properties.outputs.endpoint.value --output tsv)

# Verify role assignment
RESOURCE_ID=$(az deployment group show --resource-group $RESOURCE_GROUP --name deploy-entra-id --query properties.outputs.resourceId.value --output tsv)
az role assignment list --scope $RESOURCE_ID --assignee $SECURITY_PRINCIPAL_ID --query "[?roleDefinitionName=='Cognitive Services User'].roleDefinitionName" --output tsv

# Test authentication by getting an access token
az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

    В случае успешного выполнения вы увидите пользователя Cognitive Services из проверки назначения ролей и токен доступа из теста проверки подлинности. Теперь вы можете использовать эту конечную точку и аутентификацию Microsoft Entra ID в вашем коде.

Используйте Microsoft Entra ID в своем коде

После настройки Microsoft Entra ID в ресурсе обновите код, чтобы он использовался при обращении к конечной точке предсказаний. В следующем примере показано, как использовать модель завершения чата.

Установите пакет SDK OpenAI с помощью диспетчера пакетов, например pip:

pip install openai

Для проверки подлинности Microsoft Entra ID также установите следующее:

pip install azure-identity

Используйте пакет для работы с моделью. В следующем примере показано, как создать клиента для потребления завершения чата с Microsoft Entra ID и выполнить тестовый запрос к конечной точке завершения чата, используя развернутую модель.

Замените <resource> именем вашего ресурса Foundry. Найдите его на портале Azure или запустив az cognitiveservices account list. Замените DeepSeek-V3.1 фактическим именем развертывания.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Ожидаемые выходные данные

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Справочные материалы: OpenAI Python SDK и DefaultAzureCredential class.

Параметры идентификации при использовании Microsoft Entra ID

DefaultAzureCredential является упорядоченной последовательностью механизмов с заданной конфигурацией для аутентификации в Microsoft Entra ID. Каждый механизм проверки подлинности — это класс, производный от TokenCredential класса и известный как учетные данные. Во время выполнения DefaultAzureCredential пытается пройти проверку подлинности с помощью первых учетных данных. Если этой учетной записи не удается получить токен доступа, пробуется следующая учетная запись в последовательности, и так далее, до получения токена доступа. Таким образом, приложение может использовать разные учетные данные в разных средах без написания кода для конкретной среды.

Когда предыдущий код выполняется на локальной рабочей станции разработки, он выглядит в переменных среды для субъекта-службы приложений или локально установленных средств разработчика, например Visual Studio, для набора учетных данных разработчика. Вы можете использовать любой подход для проверки подлинности приложения для Azure ресурсов во время локальной разработки.

При развертывании в Azure этот же код также может пройти проверку подлинности приложения в других Azure ресурсах. DefaultAzureCredential может получать параметры среды и конфигурации управляемой идентичности для автоматической аутентификации в других службах.

Лучшие практики

  • Используйте детерминированные аутентификационные данные в производственных средах: настоятельно рекомендуется серьезно рассмотреть возможность перехода от использования DefaultAzureCredential к одному из следующих детерминированных решений в производственных средах.

    • Конкретная TokenCredential реализация, например ManagedIdentityCredential. См. список производных параметров.
    • Упрощенная реализация ChainedTokenCredential, оптимизированная для среды Azure, в которой выполняется ваше приложение. ChainedTokenCredential по существу создает определенный список допустимых параметров учетных данных, например ManagedIdentity для рабочей среды и VisualStudioCredential разработки.

  • Если возможно, настройте управляемые удостоверения, назначаемые системой или пользователем, для ресурсов Azure, где выполняется ваш код. Настройте доступ Microsoft Entra ID к определенным учетным записям.

Отключение проверки подлинности на основе ключей в ресурсе

Отключите проверку подлинности на основе ключей при внедрении Microsoft Entra ID и полностью устраните проблемы совместимости или варианты отката во всех приложениях, использующих эту службу. Измените disableLocalAuth свойство, чтобы отключить проверку подлинности на основе ключей.

Дополнительные сведения об отключении локальной проверки подлинности при использовании шаблона Bicep или ARM см. в разделе Как отключить локальную проверку подлинности.

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

Общие сведения о ролях в контексте ресурса в Azure

Microsoft Entra ID использует управление доступом на основе ролей (RBAC) для авторизации, которая управляет действиями, которые пользователи могут выполнять с Azure ресурсами. Роли являются центральными для управления доступом к облачным ресурсам. Роль — это коллекция разрешений, определяющих, какие действия можно выполнять для определенных Azure ресурсов. При назначении ролей пользователям, группам, служебным субъектам или управляемым удостоверениям (коллективно известным как объекты безопасности) вы управляете их доступом в вашей среде Azure к определенным ресурсам.

При назначении роли необходимо указать субъект безопасности, определение роли и область. Это сочетание называется назначением ролей. Модели Foundry — это возможность ресурсов средств Foundry, поэтому роли, назначенные этому конкретному ресурсу, управляют доступом к выводу.

Существует два типа доступа к ресурсам:

  • Доступ администрирования: действия, связанные с администрированием ресурса. Обычно эти действия изменяют состояние ресурса и ее конфигурацию. В Azure эти операции — это операции уровня управления, которые можно выполнять с помощью портала Azure, Azure CLI или инфраструктуры в виде кода. Примеры включают создание новых развертываний моделей, изменение конфигураций фильтрации содержимого, изменение версии модели, которую обслуживают, или изменение SKU-развертывания.

  • Доступ разработчика: действия, связанные с потреблением ресурсов, например вызов API завершения чата. Однако пользователь не может изменить состояние ресурса и его конфигурацию.

В Azure Microsoft Entra ID всегда выполняет операции администрирования. Роли, такие как вкладчик Cognitive Services, позволяют выполнять эти операции. Операции разработчика можно выполнять с помощью ключей доступа или Microsoft Entra ID. Роли, такие как пользователь Cognitive Services, позволяют выполнять эти операции.

Важно

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

Устранение неполадок

Прежде чем устранять неполадки, убедитесь, что у вас есть правильные разрешения:

  1. Перейдите на портал Azure и найдите ресурс Microsoft Foundry, который вы используете.

  2. На левой панели выберите элемент управления доступом (IAM) и выберите "Проверить доступ".

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

  4. Убедитесь, что роль Cognitive Services User указана (или роль, содержащая необходимые разрешения, как описано в разделе «Предварительные требования»).

    Важно

    Роли, такие как Owner или Contributor не предоставляют доступ через Microsoft Entra ID.

  5. Если роль не указана, выполните действия, описанные в этом руководстве, прежде чем продолжить.

В следующей таблице содержатся несколько сценариев, которые помогут устранить неполадки Microsoft Entra ID.

Ошибка или сценарий Корневая причина Решение
Вы используете пакет SDK Известные проблемы Прежде чем устранить неполадки, установите последнюю версию программного обеспечения, которое вы используете для подключения к службе. Ошибки проверки подлинности могут быть исправлены в более новой версии используемого программного обеспечения.
401 Principal does not have access to API/Operation Запрос указывает на правильную аутентификацию, но учетная запись пользователя не имеет необходимых разрешений для использования конечной точки для предсказаний. Убедитесь, что у вас есть:
1. Назначьте роль "Пользователь Cognitive Services" субъекту ресурсу Foundry. Обратите внимание, что пользователь OpenAI Cognitive Services предоставляет доступ только к моделям OpenAI. Владелец или участник не предоставляют доступ.
1. Подождите по крайней мере 5 минут, прежде чем выполнить первый звонок.
401 HTTP/1.1 401 PermissionDenied Запрос указывает на правильную аутентификацию, но учетная запись пользователя не имеет необходимых разрешений для использования конечной точки для предсказаний. Назначена роль "Пользователь Cognitive Services" субъекту в ресурсе Foundry. Роли, такие как администратор или участник , не предоставляют доступ к выводу. Подождите по крайней мере 5 минут, прежде чем выполнить первый звонок.
Вы используете вызовы REST API и получаете 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Запрос не проходит проверку подлинности с помощью Microsoft Entra ID. Убедитесь, что Authentication заголовок содержит допустимый токен с областью https://ai.azure.com/.default.

Следующий шаг

  • Last updated on