Azure AI 서비스에 대한 요청 인증

Azure AI 서비스에 대한 각 요청에는 인증 헤더가 포함되어야 합니다. 이 헤더는 서비스 또는 서비스 그룹에 대한 구독을 확인하는 데 사용되는 리소스 키 또는 인증 토큰을 전달합니다. 이 문서에서는 요청을 인증하는 세 가지 방법과 각각에 대한 요구 사항에 대해 알아봅니다.

• 단일 서비스 또는 다중 서비스 리소스 키로 인증
• 토큰으로 인증
• Microsoft Entra ID로 인증

필수 조건

요청하기 전에 Azure 계정과 Azure AI 서비스 구독이 필요합니다. 계정이 이미 있는 경우 다음 섹션으로 건너뜁니다. 계정이 없는 경우 몇 분 만에 설정을 완료할 수 있는 가이드가 있습니다. 다중 서비스 리소스 만들기.

계정을 생성한 후 Azure Portal에서 리소스 키를 얻을 수 있습니다.

인증 헤더

Azure AI 서비스에 사용할 수 있는 인증 헤더를 빠르게 검토해 보겠습니다.

헤더	설명
Ocp-Apim-Subscription-Key	이 헤더를 사용하여 특정 서비스에 대한 리소스 키 또는 다중 서비스 리소스 키로 인증합니다.
Ocp-Apim-Subscription-Region	이 헤더는 번역기 서비스와 함께 다중 서비스 리소스 키를 사용할 때만 필요합니다. 이 헤더를 사용하여 리소스 지역을 지정합니다.
Authorization	액세스 토큰을 사용하는 경우 이 헤더를 사용합니다. 토큰 교환을 수행하는 단계는 다음 섹션에 자세히 설명되어 있습니다. 제공된 값은 다음 형식 Bearer <TOKEN>을 따릅니다.

단일 서비스 리소스 키로 인증

첫 번째 옵션은 번역기와 같은 특정 서비스에 대한 리소스 키를 사용하여 요청을 인증하는 것입니다. 키는 만든 각 리소스에 대해 Azure Portal에서 사용할 수 있습니다. 리소스 키를 사용하여 요청을 인증하려면 Ocp-Apim-Subscription-Key 헤더로 전달되어야 합니다.

이 샘플 요청은 Ocp-Apim-Subscription-Key 헤더를 사용하는 방법을 보여 줍니다. 이 샘플을 사용할 때 유효한 리소스 키를 포함해야 한다는 점을 명심하세요.

번역기 서비스에 대한 샘플 호출입니다.

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 AI 서비스 키를 사용하는 방법을 보여줍니다.

다중 서비스 리소스 키로 인증

다중 서비스 리소스 키를 사용하여 요청을 인증할 수 있습니다. 주요 차이점은 다중 서비스 리소스 키가 특정 서비스에 연결되지 않고, 오히려 단일 키를 사용하여 여러 Azure AI 서비스에 대한 요청을 인증할 수 있다는 것입니다. 지역별 가용성, 지원되는 기능 및 가격에 대한 자세한 내용은 Azure AI 서비스 가격 책정을 참조하세요.

리소스 키는 각 요청에 Ocp-Apim-Subscription-Key 헤더로 제공됩니다.

지원되는 지역

다중 서비스 리소스 키를 사용하여 api.cognitive.microsoft.com에 요청할 때 URL에 지역을 포함해야 합니다. 예: westus.api.cognitive.microsoft.com

Azure AI 번역기와 함께 다중 서비스 리소스 키를 사용하는 경우 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

샘플 요청

번역기 서비스에 대한 샘플 호출입니다.

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 AI 서비스는 액세스 토큰을 허용하고 경우에 따라 요구합니다. 현재 다음 서비스는 액세스 토큰을 지원합니다.

• Text Translation API
• 음성 서비스: 음성 텍스트 변환 API
• 음성 서비스: 텍스트 음성 변환 API

참고 항목

QnA Maker도 인증 헤더를 사용하지만 엔드포인트 키가 필요합니다. 자세한 내용은 QnA Maker: 기술 자료 답변을 확인하세요.

Warning

액세스 토큰을 지원하는 서비스는 시간이 지남에 따라 변경될 수 있으므로 이 인증 방법을 사용하기 전에 서비스에 대한 API 참조를 확인합니다.

단일 서비스 및 다중 서비스 리소스 키 모두 인증 토큰으로 교환될 수 있습니다. 인증 토큰은 10분 동안 유효합니다. JWT(JSON Web Token) 형식으로 저장되며 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 헤더로 전달해야 합니다. 번역기 서비스에 대한 샘플 호출입니다.

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로 인증

Important

Microsoft Entra 인증은 항상 Azure 리소스의 사용자 지정 하위 기본 이름과 함께 사용해야 합니다. 지역 엔드포인트는 Microsoft Entra 인증을 지원하지 않습니다.

이전 섹션에서는 단일 서비스 또는 다중 서비스 구독 키를 사용하여 Azure AI 서비스에 대해 인증하는 방법을 보여주었습니다. 이러한 키를 이용하면 빠르고 쉽게 개발을 시작할 수 있지만 Azure RBAC(역할 기반 액세스 제어)를 필요로 하는 더 복잡한 시나리오에서는 한계가 있습니다. Microsoft Entra ID를 사용하여 인증하는 데 필요한 항목을 살펴보겠습니다.

다음 섹션에서는 Azure Cloud Shell 환경 또는 Azure CLI를 사용하여 하위 도메인을 만들고, 역할을 할당하고, Azure AI 서비스를 호출하기 위한 전달자 토큰을 얻습니다. 문제가 발생하면 Azure Cloud Shell/Azure CLI의 각 명령에 대해 사용 가능한 모든 옵션이 포함된 링크가 각 섹션에 제공됩니다.

Important

조직에서 Microsoft Entra ID를 통해 인증을 수행하는 경우 조직의 사용자가 항상 Microsoft Entra ID 를 사용해야 하므로 로컬 인증 (키 인증)을 사용하지 않도록 설정해야 합니다.

사용자 지정 하위 도메인을 사용하여 리소스 만들기

첫 번째 단계는 사용자 지정 하위 기본 만드는 것입니다. 사용자 지정 하위 도메인 이름이 없는 기존 Azure AI 서비스 리소스를 사용하려면 Azure AI 서비스 사용자 지정 하위 도메인의 지침에 따라 리소스에 대한 사용자 지정 하위 도메인을 활성화하세요.

1. 먼저 Azure Cloud Shell을 엽니다. 그런 다음 , 구독을 선택합니다.

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. 그런 다음 사용자 지정 하위 도메인을 사용하여 Azure AI 서비스 리소스를 생성합니다. 하위 도메인 이름은 전역적으로 고유해야 하며 특수 문자(예: ".", "!", ",")를 포함할 수 없습니다.

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

3. 성공하면 엔드포인트에 리소스에 고유한 하위 기본 이름이 표시됩니다.

서비스 주체에 역할 할당

이제 리소스와 연결된 사용자 지정 하위 기본 서비스 주체에 역할을 할당해야 합니다.

참고 항목

Azure 역할 할당이 전파되는 데 최대 5분이 걸릴 수 있습니다.

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 Portal에서 애플리케이션을 등록하는 경우 이 단계가 완료됩니다.

3. 마지막 단계는 "Cognitive Services 사용자" 역할을 서비스 주체(리소스로 범위 지정)에 할당하는 것입니다. 역할을 할당하면 서비스 주체에게 이 리소스에 대한 액세스 권한을 부여합니다. 동일한 서비스 주체에게 구독에서 여러 리소스에 대한 액세스 권한을 부여할 수 있습니다.

   참고 항목

   서비스 주체의 ObjectId는 애플리케이션의 ObjectId가 아니라 사용됩니다. ACCOUNT_ID는 사용자가 만든 Azure AI 서비스 계정의 Azure 리소스 ID입니다. Azure Portal에서 리소스의 "속성"에서 Azure 리소스 ID를 찾을 수 있습니다.

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

샘플 요청

이 샘플에서는 암호가 서비스 주체를 인증하는 데 사용됩니다. 그런 다음, 제공된 토큰을 사용하여 Computer Vision 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 KeyVault와 같은 솔루션과 통합하는 것입니다.

3. Computer Vision 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 애플리케이션을 통해 권한을 위임하여 사용자 보안 주체도 지원됩니다. 이 경우 암호나 인증서 대신 토큰을 획득할 때 사용자에게 2단계 인증을 요청하는 메시지가 표시됩니다.

관리 ID에 대한 액세스 권한 부여

Azure AI 서비스는 Azure 리소스에 대한 관리 ID를 사용하여 Microsoft Entra 인증을 지원합니다. Azure 리소스에 대한 관리 ID는 Azure VM(가상 머신), 함수 앱, 가상 머신 확장 집합 및 기타 서비스에서 실행되는 애플리케이션에서 Microsoft Entra 자격 증명을 사용하여 Azure AI 서비스 리소스에 대한 액세스 권한을 부여할 수 있습니다. Microsoft Entra 인증과 함께 Azure 리소스에 대한 관리 ID를 사용하면 클라우드에서 실행되는 애플리케이션에 자격 증명을 저장하지 않아도 됩니다.

VM에서 관리 ID 사용

Azure 리소스에 대한 관리 ID를 사용하여 VM에서 Azure AI 서비스 리소스에 대한 액세스 권한을 부여하려면 먼저 VM에서 Azure 리소스에 대한 관리 ID를 사용하도록 설정해야 합니다. Azure 리소스의 관리 ID를 사용하도록 설정하는 방법을 알아보려면 다음을 참조하세요.

• Azure Portal
• Azure PowerShell
• Azure CLI
• Azure Resource Manager 템플릿
• Azure Resource Manager 클라이언트 라이브러리

관리 ID에 대한 자세한 내용은 Azure 리소스의 관리 ID를 참조하세요.

Azure 키 자격 증명 모음을 사용하여 자격 증명에 안전하게 액세스

Azure Key Vault를 사용하여 Azure AI 서비스 애플리케이션을 안전하게 개발할 수 있습니다. Key Vault를 사용하면 인증 자격 증명을 클라우드에 저장할 수 있으며 애플리케이션에 보안 정보를 저장하지 않으므로 비밀이 실수로 유출될 가능성을 줄일 수 있습니다.

인증이 Microsoft Entra ID를 통해 수행됩니다. 권한 부여는 Azure RBAC(Azure 역할 기반 액세스 제어) 또는 Key Vault 액세스 정책을 통해 수행할 수 있습니다. Azure RBAC는 자격 증명 모음의 관리와 자격 증명 모음에 저장된 데이터에 액세스하는 데 모두 사용할 수 있으며, 키 자격 증명 모음 액세스 정책은 자격 증명 모음에 저장된 데이터에 액세스하려고 할 때만 사용할 수 있습니다.

참고 항목

• Azure AI 서비스란?
• Azure AI 서비스 가격
• 사용자 지정 하위 기본